110 lines
6.2 KiB
Plaintext
110 lines
6.2 KiB
Plaintext
---
|
|
title: Field Hooks
|
|
label: Fields
|
|
order: 30
|
|
desc: Hooks can be added to any fields, and optionally modify the return value of the field before the operation continues.
|
|
keywords: hooks, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
|
|
---
|
|
|
|
Field-level hooks offer incredible potential for encapsulating your logic. They help to isolate concerns and package up functionalities to be easily reusable across your projects.
|
|
|
|
**Example use cases include:**
|
|
|
|
- Automatically add an `owner` relationship to a Document based on the `req.user.id`
|
|
- Encrypt / decrypt a sensitive field using `beforeValidate` and `afterRead` hooks
|
|
- Auto-generate field data using a `beforeValidate` hook
|
|
- Format incoming data such as kebab-casing a document `slug` with `beforeValidate`
|
|
- Restrict updating a document to only once every X hours using the `beforeChange` hook
|
|
|
|
**All field types provide the following hooks:**
|
|
|
|
- `beforeValidate`
|
|
- `beforeChange`
|
|
- `afterChange`
|
|
- `afterRead`
|
|
|
|
## Config
|
|
|
|
Example field configuration:
|
|
```ts
|
|
import { Field } from 'payload/types';
|
|
|
|
const ExampleField: Field = {
|
|
name: 'name',
|
|
type: 'text',
|
|
// highlight-start
|
|
hooks: {
|
|
beforeValidate: [(args) => {...}],
|
|
beforeChange: [(args) => {...}],
|
|
afterChange: [(args) => {...}],
|
|
afterRead: [(args) => {...}],
|
|
}
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
## Arguments and return values
|
|
|
|
All field-level hooks are formatted to accept the same arguments, although some arguments may be `undefined` based on which field hook you are utilizing.
|
|
|
|
<Banner type="success">
|
|
<strong>Tip:</strong><br />
|
|
It's a good idea to conditionally scope your logic based on which operation is executing. For example, if you are writing a <strong>beforeChange</strong> hook, you may want to perform different logic based on if the current <strong>operation</strong> is <strong>create</strong> or <strong>update</strong>.
|
|
</Banner>
|
|
|
|
#### Arguments
|
|
|
|
Field Hooks receive one `args` argument that contains the following properties:
|
|
|
|
| Option | Description |
|
|
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| **`data`** | The data passed to update the document within `create` and `update` operations, and the full document itself in the `afterRead` hook. |
|
|
| **`siblingData`** | The sibling data passed to a field that the hook is running against. |
|
|
| **`findMany`** | Boolean to denote if this hook is running against finding one, or finding many within the `afterRead` hook. |
|
|
| **`operation`** | A string relating to which operation the field type is currently executing within. Useful within `beforeValidate`, `beforeChange`, and `afterChange` hooks to differentiate between `create` and `update` operations. |
|
|
| **`originalDoc`** | The full original document in `update` operations. In the `afterChange` hook, this is the resulting document of the operation. |
|
|
| **`previousDoc`** | The document before changes were applied, only in `afterChange` hooks. |
|
|
| **`previousSiblingDoc`** | The sibling data from the previous document in `afterChange` hook. |
|
|
| **`req`** | The Express `request` object. It is mocked for Local API operations. |
|
|
| **`value`** | The value of the field. |
|
|
| **`previousValue`** | The previous value of the field, before changes were applied, only in `afterChange` hooks. |
|
|
|
|
#### Return value
|
|
|
|
All field hooks can optionally modify the return value of the field before the operation continues. Field Hooks may optionally return the value that should be used within the field.
|
|
|
|
<Banner type="warning">
|
|
<strong>Important</strong><br/>
|
|
Due to GraphQL's typed nature, you should never change the type of data that you return from a field, otherwise GraphQL will produce errors. If you need to change the shape or type of data, reconsider Field Hooks and instead evaluate if Collection / Global hooks might suit you better.
|
|
</Banner>
|
|
|
|
## TypeScript
|
|
|
|
Payload exports a type for field hooks which can be accessed and used as follows:
|
|
|
|
```ts
|
|
import type { FieldHook } from 'payload/types';
|
|
|
|
// Field hook type is a generic that takes three arguments:
|
|
// 1: The document type
|
|
// 2: The value type
|
|
// 3: The sibling data type
|
|
|
|
type ExampleFieldHook = FieldHook<ExampleDocumentType, string, SiblingDataType>;
|
|
|
|
const exampleFieldHook: ExampleFieldHook = (args) => {
|
|
const {
|
|
value, // Typed as `string` as shown above
|
|
data, // Typed as a Partial of your ExampleDocumentType
|
|
siblingData, // Typed as a Partial of SiblingDataType
|
|
originalDoc, // Typed as ExampleDocumentType
|
|
operation,
|
|
req,
|
|
} = args;
|
|
|
|
// Do something here...
|
|
|
|
return value; // should return a string as typed above, undefined, or null
|
|
}
|
|
```
|