b383eb65c6
* feat: autolabel fields when omitted * feat: handle autolabel in graphql mutation build * feat: autolabel blocks * test: add required slug field to blocks * feat: handle graphql names when label is false * feat: adds relationship field to test searchable input * feat: handle block cell type labeling pluralization * docs: remove all explicit labeling, no longer needed * fix: falsey column labels, allows false array labels * fix: client tests * fix: auto-labels globals * docs: globals auto-labeling and hooks clarification * fix; proper object type naming Co-authored-by: James <james@trbl.design>
73 lines
3.2 KiB
Plaintext
73 lines
3.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:
|
|
```js
|
|
{
|
|
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 |
|
|
| ----------------- | -------------|
|
|
| **`value`** | The value of the field. |
|
|
| **`data`** | The data passed to update the field with in `create` and `update` operations, and the full document itself in the `afterRead` hook. |
|
|
| **`originalDoc`** | The full original document in `update` operations. |
|
|
| **`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. |
|
|
| **`req`** | The Express `request` object. It is mocked for Local API operations. |
|
|
|
|
#### 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>
|