docs: rewrites fields overview doc (#7065)
This commit is contained in:
Jacob Fletcher
@@ -17,18 +17,18 @@ All Custom Components in Payload are [React Server Components](https://react.dev
|
|||||||
|
|
||||||
There are four main types of Custom Components in Payload:
|
There are four main types of Custom Components in Payload:
|
||||||
|
|
||||||
- [Root Components](#custom-root-components)
|
- [Root Components](#root-components)
|
||||||
- [Collection Components](#custom-collection-components)
|
- [Collection Components](#collection-components)
|
||||||
- [Global Components](#custom-global-components)
|
- [Global Components](#global-components)
|
||||||
- [Field Components](./fields)
|
- [Field Components](./fields)
|
||||||
|
|
||||||
To swap in your own Custom Component, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then [author your React component(s)](#building-custom-components) accordingly.
|
To swap in your own Custom Component, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then [author your React component(s)](#building-custom-components) accordingly.
|
||||||
|
|
||||||
## Custom Root Components
|
## Root Components
|
||||||
|
|
||||||
Root Components are those that effect the [Admin Panel](./overview) generally, such as the logo or the main nav.
|
Root Components are those that effect the [Admin Panel](./overview) generally, such as the logo or the main nav.
|
||||||
|
|
||||||
To override Root Components, use the `admin.components` property of the [Payload Config](../getting-started/overview):
|
To override Root Components, use the `admin.components` property in your [Payload Config](../getting-started/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
@@ -68,14 +68,14 @@ The following options are available:
|
|||||||
| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). |
|
| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). |
|
||||||
|
|
||||||
<Banner type="success">
|
<Banner type="success">
|
||||||
<strong>Note:</strong> You can also use the `admin.components` property on any _[Collection](#custom-collection-components) or [Global](#custom-global-components)_.
|
<strong>Note:</strong> You can also use the `admin.components` property in your _[Collection](#collection-components) or [Global](#global-components)_.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
### Custom Providers
|
### Custom Providers
|
||||||
|
|
||||||
As you add more and more Custom Components to your [Admin Panel](./overview), you may find it helpful to add additional [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context)(s). Payload allows you to inject your own context providers in your app where you can export your own custom hooks, etc.
|
As you add more and more Custom Components to your [Admin Panel](./overview), you may find it helpful to add additional [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context)(s). Payload allows you to inject your own context providers in your app where you can export your own custom hooks, etc.
|
||||||
|
|
||||||
To add a Custom Provider, use the `admin.components.providers` property of the [Payload Config](../getting-started/overview):
|
To add a Custom Provider, use the `admin.components.providers` property in your [Payload Config](../getting-started/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
@@ -115,11 +115,11 @@ export const useMyCustomContext = () => useContext(MyCustomContext)
|
|||||||
<strong>Reminder:</strong> Custom Providers are by definition Client Components. This means they must include the `use client` directive at the top of their files and cannot use server-only code.
|
<strong>Reminder:</strong> Custom Providers are by definition Client Components. This means they must include the `use client` directive at the top of their files and cannot use server-only code.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
## Custom Collection Components
|
## Collection Components
|
||||||
|
|
||||||
Collection Components are those that effect [Collection](../configuration/collections)-specific UI within the [Admin Panel](./overview), such as the save button or the List View.
|
Collection Components are those that effect [Collection](../configuration/collections)-specific UI within the [Admin Panel](./overview), such as the save button or the List View.
|
||||||
|
|
||||||
To override Collection Components, use the `admin.components` property of your [Collection Config](../configuration/collections):
|
To override Collection Components, use the `admin.components` property in your [Collection Config](../configuration/collections):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedCollectionConfig } from 'payload'
|
import type { SanitizedCollectionConfig } from 'payload'
|
||||||
@@ -154,11 +154,11 @@ The following options are available:
|
|||||||
| **`edit.PreviewButton`** | Replace the default `Preview` button with a Custom Component. |
|
| **`edit.PreviewButton`** | Replace the default `Preview` button with a Custom Component. |
|
||||||
| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). |
|
| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). |
|
||||||
|
|
||||||
## Custom Global Components
|
## Global Components
|
||||||
|
|
||||||
Global Components are those that effect [Global](../configuration/globals)-specific UI within the [Admin Panel](./overview), such as the save button or the Edit View.
|
Global Components are those that effect [Global](../configuration/globals)-specific UI within the [Admin Panel](./overview), such as the save button or the Edit View.
|
||||||
|
|
||||||
To override Global Components, use the `admin.components` property of your [Global Config](../configuration/globals):
|
To override Global Components, use the `admin.components` property in your [Global Config](../configuration/globals):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedGlobalConfig } from 'payload'
|
import type { SanitizedGlobalConfig } from 'payload'
|
||||||
@@ -224,7 +224,7 @@ Each Custom Component receives the following props by default:
|
|||||||
Custom Components also receive various other props that are specific to the context in which the Custom Component is being rendered. For example, [Custom Views](./views) receive the `user` prop. For a full list of available props, consult the documentation related to the specific component you are working with.
|
Custom Components also receive various other props that are specific to the context in which the Custom Component is being rendered. For example, [Custom Views](./views) receive the `user` prop. For a full list of available props, consult the documentation related to the specific component you are working with.
|
||||||
|
|
||||||
<Banner type="success">
|
<Banner type="success">
|
||||||
See [Root Components](#custom-root-components), [Collection Components](#custom-collection-components), [Global Components](#custom-global-components), or [Field Components](#custom-field-components) for a complete list of all available components.
|
See [Root Components](#root-components), [Collection Components](#collection-components), [Global Components](#global-components), or [Field Components](#custom-field-components) for a complete list of all available components.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
### Client Components
|
### Client Components
|
||||||
|
|||||||
@@ -6,7 +6,7 @@ desc:
|
|||||||
keywords:
|
keywords:
|
||||||
---
|
---
|
||||||
|
|
||||||
[Fields](../fields/overview) within the [Admin Panel](./overview) can be endlessly customized in appearance and behavior without affecting their underlying data structure. Using [Conditional Logic](#conditional-logic), [Custom Field Components](#custom-field-components), [Custom Validations](../fields/overview#validation), and more, fields are designed to withstand heavy modification or even complete replacement.
|
[Fields](../fields/overview) within the [Admin Panel](./overview) can be endlessly customized in their appearance and behavior without affecting their underlying data structure. Fields are designed to withstand heavy modification or even complete replacement through the use of [Custom Field Components](#field-components), [Conditional Logic](#conditional-logic), [Custom Validations](../fields/overview#validation), and more.
|
||||||
|
|
||||||
For example, your app might need to render a specific interface that Payload does not inherently support, such as a color picker. To do this, you could replace the default [Text Field](../fields/text) input with your own user-friendly component that formats the data into a valid color value.
|
For example, your app might need to render a specific interface that Payload does not inherently support, such as a color picker. To do this, you could replace the default [Text Field](../fields/text) input with your own user-friendly component that formats the data into a valid color value.
|
||||||
|
|
||||||
@@ -56,7 +56,7 @@ The following options are available:
|
|||||||
| **`disableListFilter`** | Set `disableListFilter` to `true` to prevent fields from appearing in the list view filter options. |
|
| **`disableListFilter`** | Set `disableListFilter` to `true` to prevent fields from appearing in the list view filter options. |
|
||||||
| **`hidden`** | Will transform the field into a `hidden` input type. Its value will still submit with requests in the Admin Panel, but the field itself will not be visible to editors. |
|
| **`hidden`** | Will transform the field into a `hidden` input type. Its value will still submit with requests in the Admin Panel, but the field itself will not be visible to editors. |
|
||||||
|
|
||||||
## Custom Field Components
|
## Field Components
|
||||||
|
|
||||||
Within the [Admin Panel](./overview), fields are rendered in three distinct places:
|
Within the [Admin Panel](./overview), fields are rendered in three distinct places:
|
||||||
|
|
||||||
@@ -64,7 +64,7 @@ Within the [Admin Panel](./overview), fields are rendered in three distinct plac
|
|||||||
- [Cell](#the-cell-component) - The table cell component rendered in the List View.
|
- [Cell](#the-cell-component) - The table cell component rendered in the List View.
|
||||||
- [Filter](#the-filter-component) - The filter component rendered in the List View.
|
- [Filter](#the-filter-component) - The filter component rendered in the List View.
|
||||||
|
|
||||||
To easily swap in Field Components with your own, use the `admin.components` property of any [Field Config](../fields/overview):
|
To easily swap in Field Components with your own, use the `admin.components` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { CollectionConfig } from 'payload'
|
import type { CollectionConfig } from 'payload'
|
||||||
@@ -104,7 +104,7 @@ _\* **`beforeInput`** and **`afterInput`** are only supported in fields that do
|
|||||||
|
|
||||||
The Field Component is the actual form field rendered in the Edit View. This is the input that user's will interact with when editing a document.
|
The Field Component is the actual form field rendered in the Edit View. This is the input that user's will interact with when editing a document.
|
||||||
|
|
||||||
To easily swap in your own Field Component, use the `admin.components.Field` property of your [Field Config](../fields/overview):
|
To easily swap in your own Field Component, use the `admin.components.Field` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { CollectionConfig } from 'payload'
|
import type { CollectionConfig } from 'payload'
|
||||||
@@ -137,7 +137,7 @@ All Field Components receive the following props:
|
|||||||
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
| **`AfterInput`** | The rendered result of the `admin.components.afterInput` property. [More details](#afterinput-and-beforeinput). |
|
| **`AfterInput`** | The rendered result of the `admin.components.afterInput` property. [More details](#afterinput-and-beforeinput). |
|
||||||
| **`BeforeInput`** | The rendered result of the `admin.components.beforeInput` property. [More details](#afterinput-and-beforeinput). |
|
| **`BeforeInput`** | The rendered result of the `admin.components.beforeInput` property. [More details](#afterinput-and-beforeinput). |
|
||||||
| **`CustomDescription`** | The rendered result of the `description` property. [More details](#the-description-component). |
|
| **`CustomDescription`** | The rendered result of the `admin.components.Description` property. [More details](#the-description-component). |
|
||||||
| **`CustomError`** | The rendered result of the `admin.components.Error` property. [More details](#the-error-component). |
|
| **`CustomError`** | The rendered result of the `admin.components.Error` property. [More details](#the-error-component). |
|
||||||
| **`CustomLabel`** | The rendered result of the `admin.components.Label` property. [More details](#the-label-component).
|
| **`CustomLabel`** | The rendered result of the `admin.components.Label` property. [More details](#the-label-component).
|
||||||
| **`path`** | The static path of the field at render time. [More details](./hooks#usefieldprops). |
|
| **`path`** | The static path of the field at render time. [More details](./hooks#usefieldprops). |
|
||||||
@@ -197,7 +197,7 @@ export const CustomTextField: React.FC = () => {
|
|||||||
|
|
||||||
The Cell Component is rendered in the table of the List View. It represents the value of the field when displayed in a table cell.
|
The Cell Component is rendered in the table of the List View. It represents the value of the field when displayed in a table cell.
|
||||||
|
|
||||||
To easily swap in your own Cell Component, use the `admin.components.Cell` property of your [Field Config](../fields/overview):
|
To easily swap in your own Cell Component, use the `admin.components.Cell` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { Field } from 'payload'
|
import type { Field } from 'payload'
|
||||||
@@ -248,7 +248,7 @@ All Cell Components receive the following props:
|
|||||||
|
|
||||||
The Label Component is rendered anywhere a field needs to be represented by a label. This is typically used in the Edit View, but can also be used in the List View and elsewhere.
|
The Label Component is rendered anywhere a field needs to be represented by a label. This is typically used in the Edit View, but can also be used in the List View and elsewhere.
|
||||||
|
|
||||||
To easily swap in your own Label Component, use the `admin.components.Label` property of your [Field Config](../fields/overview):
|
To easily swap in your own Label Component, use the `admin.components.Label` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { Field } from 'payload'
|
import type { Field } from 'payload'
|
||||||
@@ -283,7 +283,7 @@ All Label Components receive the following props:
|
|||||||
|
|
||||||
The Error Component is rendered when a field fails validation. It is typically displayed beneath the field input in a visually-compelling style.
|
The Error Component is rendered when a field fails validation. It is typically displayed beneath the field input in a visually-compelling style.
|
||||||
|
|
||||||
To easily swap in your own Error Component, use the `admin.components.Error` property of your [Field Config](../fields/overview):
|
To easily swap in your own Error Component, use the `admin.components.Error` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { Field } from 'payload'
|
import type { Field } from 'payload'
|
||||||
@@ -322,7 +322,7 @@ A description can be configured in three ways:
|
|||||||
- As a function which returns a string. [More details](#description-functions).
|
- As a function which returns a string. [More details](#description-functions).
|
||||||
- As a React component. [More details](#the-description-component).
|
- As a React component. [More details](#the-description-component).
|
||||||
|
|
||||||
To easily add a Custom Description to a field, use the `admin.description` property of your [Field Config](../fields/overview):
|
To easily add a Custom Description to a field, use the `admin.description` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedCollectionConfig } from 'payload'
|
import type { SanitizedCollectionConfig } from 'payload'
|
||||||
@@ -381,7 +381,7 @@ All Description Functions receive the following arguments:
|
|||||||
|
|
||||||
Alternatively to the [Description Property](#the-description-property), you can also use a [Custom Component](./components) as the Field Description. This can be useful when you need to provide more complex feedback to the user, such as rendering dynamic field values or other interactive elements.
|
Alternatively to the [Description Property](#the-description-property), you can also use a [Custom Component](./components) as the Field Description. This can be useful when you need to provide more complex feedback to the user, such as rendering dynamic field values or other interactive elements.
|
||||||
|
|
||||||
To easily add a Description Component to a field, use the `admin.components.Description` property of your [Field Config](../fields/overview):
|
To easily add a Description Component to a field, use the `admin.components.Description` property in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedCollectionConfig } from 'payload'
|
import type { SanitizedCollectionConfig } from 'payload'
|
||||||
@@ -421,7 +421,7 @@ All Description Components receive the following props:
|
|||||||
|
|
||||||
With these properties you can add multiple components _before_ and _after_ the input element, as their name suggests. This is useful when you need to render additional elements alongside the field without replacing the entire field component.
|
With these properties you can add multiple components _before_ and _after_ the input element, as their name suggests. This is useful when you need to render additional elements alongside the field without replacing the entire field component.
|
||||||
|
|
||||||
To add components before and after the input element, use the `admin.components.beforeInput` and `admin.components.afterInput` properties of your [Field Config](../fields/overview):
|
To add components before and after the input element, use the `admin.components.beforeInput` and `admin.components.afterInput` properties in your [Field Config](../fields/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedCollectionConfig } from 'payload'
|
import type { SanitizedCollectionConfig } from 'payload'
|
||||||
|
|||||||
@@ -147,7 +147,7 @@ You have full control over the routes that Payload binds itself to. This include
|
|||||||
|
|
||||||
Root-level routes are those that are not behind the `/admin` path, such as the [REST API](../rest-api/overview) and [GraphQL API](../graphql/overview), or the root path of the Admin Panel itself.
|
Root-level routes are those that are not behind the `/admin` path, such as the [REST API](../rest-api/overview) and [GraphQL API](../graphql/overview), or the root path of the Admin Panel itself.
|
||||||
|
|
||||||
To customize root-level routes, use the `routes` property of your [Payload Config](../configuration/overview):
|
To customize root-level routes, use the `routes` property in your [Payload Config](../configuration/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
@@ -183,7 +183,7 @@ The following options are available:
|
|||||||
|
|
||||||
Admin-level routes are those behind the `/admin` path. These are the routes that are part of the Admin Panel itself, such as the user's account page, the login page, etc.
|
Admin-level routes are those behind the `/admin` path. These are the routes that are part of the Admin Panel itself, such as the user's account page, the login page, etc.
|
||||||
|
|
||||||
To customize admin-level routes, use the `admin.routes` property of your [Payload Config](../configuration/overview):
|
To customize admin-level routes, use the `admin.routes` property in your [Payload Config](../configuration/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
|
|||||||
@@ -10,14 +10,14 @@ Views are the individual pages that make up the [Admin Panel](./overview), such
|
|||||||
|
|
||||||
Within the Admin Panel, there are four types of views:
|
Within the Admin Panel, there are four types of views:
|
||||||
|
|
||||||
- [Root Views](#custom-root-views)
|
- [Root Views](#root-views)
|
||||||
- [Collection Views](#custom-collection-views)
|
- [Collection Views](#collection-views)
|
||||||
- [Global Views](#custom-global-views)
|
- [Global Views](#global-views)
|
||||||
- [Document Views](#custom-document-views)
|
- [Document Views](#document-views)
|
||||||
|
|
||||||
To swap in your own Custom Views, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then [author your React component(s)](#building-custom-views) accordingly.
|
To swap in your own Custom Views, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then [author your React component(s)](#building-custom-views) accordingly.
|
||||||
|
|
||||||
## Custom Root Views
|
## Root Views
|
||||||
|
|
||||||
Root Views are the main views of the [Admin Panel](./overview). These are views that are scoped directly under the `/admin` route, such as the Dashboard or Account views.
|
Root Views are the main views of the [Admin Panel](./overview). These are views that are scoped directly under the `/admin` route, such as the Dashboard or Account views.
|
||||||
|
|
||||||
@@ -83,7 +83,7 @@ const config = buildConfig({
|
|||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
The above example shows how to add a new [Root View](#custom-root-views), but the pattern is the same for [Collection Views](#custom-collection-views), [Global Views](#custom-global-views), and [Document Views](#custom-document-views). For help on how to build your own Custom Views, see [Building Custom Views](#building-custom-views).
|
The above example shows how to add a new [Root View](#root-views), but the pattern is the same for [Collection Views](#collection-views), [Global Views](#global-views), and [Document Views](#document-views). For help on how to build your own Custom Views, see [Building Custom Views](#building-custom-views).
|
||||||
|
|
||||||
<Banner type="warning">
|
<Banner type="warning">
|
||||||
<strong>Note:</strong>
|
<strong>Note:</strong>
|
||||||
@@ -94,7 +94,7 @@ The above example shows how to add a new [Root View](#custom-root-views), but th
|
|||||||
route.
|
route.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
## Custom Collection Views
|
## Collection Views
|
||||||
|
|
||||||
Collection Views are views that are scoped under the `/collections` route, such as the Collection List and Document Edit views.
|
Collection Views are views that are scoped under the `/collections` route, such as the Collection List and Document Edit views.
|
||||||
|
|
||||||
@@ -119,14 +119,14 @@ _For details on how to build Custom Views, see [Building Custom Views](#building
|
|||||||
|
|
||||||
<Banner type="warning">
|
<Banner type="warning">
|
||||||
<strong>Note:</strong>
|
<strong>Note:</strong>
|
||||||
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#custom-document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
|
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
The following options are available:
|
The following options are available:
|
||||||
|
|
||||||
| Property | Description |
|
| Property | Description |
|
||||||
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
|
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||||
| **`Edit`** | The Edit View is used to edit a single document for any given Collection. [More details](#custom-document-views). |
|
| **`Edit`** | The Edit View is used to edit a single document for any given Collection. [More details](#document-views). |
|
||||||
| **`List`** | The List View is used to show a list of documents for any given Collection. |
|
| **`List`** | The List View is used to show a list of documents for any given Collection. |
|
||||||
|
|
||||||
<Banner type="success">
|
<Banner type="success">
|
||||||
@@ -134,11 +134,11 @@ The following options are available:
|
|||||||
You can also add _new_ Collection Views to the config by adding a new key to the `views` object with at least a `path` and `Component` property. See [Adding New Views](#adding-new-views) for more information.
|
You can also add _new_ Collection Views to the config by adding a new key to the `views` object with at least a `path` and `Component` property. See [Adding New Views](#adding-new-views) for more information.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
## Custom Global Views
|
## Global Views
|
||||||
|
|
||||||
Global Views are views that are scoped under the `/globals` route, such as the Document Edit View.
|
Global Views are views that are scoped under the `/globals` route, such as the Document Edit View.
|
||||||
|
|
||||||
To easily swap out Global Views with your own or [create entirely new ones](#adding-new-views), use the `admin.components.views` property of your [Global Config](../globals/overview):
|
To easily swap out Global Views with your own or [create entirely new ones](#adding-new-views), use the `admin.components.views` property in your [Global Config](../globals/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedGlobalConfig } from 'payload'
|
import type { SanitizedGlobalConfig } from 'payload'
|
||||||
@@ -159,25 +159,25 @@ _For details on how to build Custom Views, see [Building Custom Views](#building
|
|||||||
|
|
||||||
<Banner type="warning">
|
<Banner type="warning">
|
||||||
<strong>Note:</strong>
|
<strong>Note:</strong>
|
||||||
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#custom-document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
|
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
The following options are available:
|
The following options are available:
|
||||||
|
|
||||||
| Property | Description |
|
| Property | Description |
|
||||||
| ---------- | ------------------------------------------------------------------- |
|
| ---------- | ------------------------------------------------------------------- |
|
||||||
| **`Edit`** | The Edit View is used to edit a single document for any given Global. [More details](#custom-document-views). |
|
| **`Edit`** | The Edit View is used to edit a single document for any given Global. [More details](#document-views). |
|
||||||
|
|
||||||
<Banner type="success">
|
<Banner type="success">
|
||||||
<strong>Note:</strong>
|
<strong>Note:</strong>
|
||||||
You can also add _new_ Global Views to the config by adding a new key to the `views` object with at least a `path` and `Component` property. See [Adding New Views](#adding-new-views) for more information.
|
You can also add _new_ Global Views to the config by adding a new key to the `views` object with at least a `path` and `Component` property. See [Adding New Views](#adding-new-views) for more information.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
## Custom Document Views
|
## Document Views
|
||||||
|
|
||||||
Document Views are views that are scoped under the `/collections/:collectionSlug/:id` or the `/globals/:globalSlug` route, such as the Edit View or the API View. All Document Views keep their overall structure across navigation changes, such as their title and tabs, and replace only the content below.
|
Document Views are views that are scoped under the `/collections/:collectionSlug/:id` or the `/globals/:globalSlug` route, such as the Edit View or the API View. All Document Views keep their overall structure across navigation changes, such as their title and tabs, and replace only the content below.
|
||||||
|
|
||||||
To easily swap out Document Views with your own, or to [create entirely new ones](#adding-new-document-views), use the `admin.components.views.Edit[key]` property of either your [Collection Config](../collections/overview) or [Global Config](../globals/overview):
|
To easily swap out Document Views with your own, or to [create entirely new ones](#adding-new-document-views), use the `admin.components.views.Edit[key]` property in your [Collection Config](../collections/overview) or [Global Config](../globals/overview):
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { SanitizedCollectionConfig } from 'payload'
|
import type { SanitizedCollectionConfig } from 'payload'
|
||||||
@@ -202,7 +202,7 @@ _For details on how to build Custom Views, see [Building Custom Views](#building
|
|||||||
|
|
||||||
<Banner type="warning">
|
<Banner type="warning">
|
||||||
<strong>Note:</strong>
|
<strong>Note:</strong>
|
||||||
If you need to replace the _entire_ Edit View, including _all_ nested Document Views, use the `Edit` key itself. See [Custom Collection Views](#custom-collection-views) or [Custom Global Views](#custom-global-views) for more information.
|
If you need to replace the _entire_ Edit View, including _all_ nested Document Views, use the `Edit` key itself. See [Custom Collection Views](#collection-views) or [Custom Global Views](#global-views) for more information.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
The following options are available:
|
The following options are available:
|
||||||
|
|||||||
@@ -6,154 +6,278 @@ desc: Fields are the building blocks of Payload, find out how to add or remove a
|
|||||||
keywords: overview, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
keywords: overview, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
||||||
---
|
---
|
||||||
|
|
||||||
<Banner type="info">
|
Fields are the building blocks of Payload. Both [Collections](../configuration/collections) and [Globals](../configuration/globals) use fields to define the shape of the data that will be stored in the [Database](../database/overview), as well as automatically generate the corresponding UI within the [Admin Panel](../admin/overview).
|
||||||
Fields are the building blocks of Payload. Collections and Globals both use Fields to define the
|
|
||||||
shape of the data that they store. Payload offers a wide variety of field types - both simple and
|
There are many [Field Types](#field-types) to choose from, ranging anywhere from simple text strings to nested arrays and blocks. Most fields save data to the database, while others are strictly presentational. Fields can have [Custom Validations](#validations), [Conditional Logic](../admin/fields#conditional-logic), [Access Control](#field-level-access-control), [Hooks](#field-level-hooks), and so much more.
|
||||||
complex.
|
|
||||||
|
<Banner type="success">
|
||||||
|
You can fully customize the appearance and behavior of all fields within the Admin Panel. [More details](../admin/fields).
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
Payload Fields define the shape of the data that will be stored in the [Database](../database/overview) as well as automatically construct the corresponding UI within the [Admin Panel](../admin/overview). Fields are defined as an array on [Collections](../configuration/collections) or [Globals](../configuration/globals) via the `fields` key.
|
|
||||||
|
|
||||||
There are many [field types](#field-types) to choose from, each of which allow you to write [Custom Validation](#validation) functions, [Conditional Logic](../admin/fields#conditional-logic), [Field-level Access Control](#field-level-access-control), [Field-level Hooks](#field-level-hooks), and so much more. You can also customize the appearance and behavior of fields in the Admin Panel, more details [here](../admin/fields).
|
|
||||||
|
|
||||||
The required `type` property on a field determines what values it can accept, how it is presented in the API, and how the field will be rendered in the admin interface.
|
|
||||||
|
|
||||||
**Simple collection with two fields:**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import { CollectionConfig } from 'payload/types'
|
|
||||||
|
|
||||||
export const Page: CollectionConfig = {
|
|
||||||
slug: 'pages',
|
|
||||||
fields: [
|
|
||||||
{
|
|
||||||
name: 'myField',
|
|
||||||
type: 'text', // highlight-line
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'otherField',
|
|
||||||
type: 'checkbox', // highlight-line
|
|
||||||
},
|
|
||||||
],
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Field Types
|
## Field Types
|
||||||
|
|
||||||
- [Array](/docs/fields/array) - for repeating content, supports nested fields
|
Payload provides a wide variety of built-in Field Types, each with its own unique properties and behaviors that determine which values it can accept, how it is presented in the API, and how it will be rendered in the [Admin Panel](../admin/overview).
|
||||||
- [Blocks](/docs/fields/blocks) - block-based fields, allowing powerful layout creation
|
|
||||||
- [Checkbox](/docs/fields/checkbox) - boolean true / false checkbox
|
|
||||||
- [Code](/docs/fields/code) - code editor that saves a string to the database
|
|
||||||
- [Collapsible](/docs/fields/collapsible) - used for admin layout, nest fields within a collapsible component
|
|
||||||
- [Date](/docs/fields/date) - date / time field that saves a timestamp
|
|
||||||
- [Email](/docs/fields/email) - validates the entry is a properly formatted email
|
|
||||||
- [Group](/docs/fields/group) - nest fields within an object
|
|
||||||
- [JSON](/docs/fields/json) - saves actual JSON in the database
|
|
||||||
- [Number](/docs/fields/number) - field that enforces that its value be a number
|
|
||||||
- [Point](/docs/fields/point) - geometric coordinates for location data
|
|
||||||
- [Radio](/docs/fields/radio) - radio button group, allowing only one value to be selected
|
|
||||||
- [Relationship](/docs/fields/relationship) - assign relationships to other collections
|
|
||||||
- [Rich Text](/docs/fields/rich-text) - fully extensible Rich Text editor
|
|
||||||
- [Row](/docs/fields/row) - used for admin field layout, no effect on data shape
|
|
||||||
- [Select](/docs/fields/select) - dropdown / picklist style value selector
|
|
||||||
- [Tabs](/docs/fields/tabs) - used for admin layout, nest fields within tabs
|
|
||||||
- [Text](/docs/fields/text) - simple text input
|
|
||||||
- [Textarea](/docs/fields/textarea) - allows a bit larger of a text editor
|
|
||||||
- [Upload](/docs/fields/upload) - allows local file and image upload
|
|
||||||
- [UI](/docs/fields/ui) - inject your own custom components and do whatever you need
|
|
||||||
|
|
||||||
## Field-level Hooks
|
To configure fields, use the `fields` property in your [Collection](../configuration/collections) or [Global](../configuration/globals) config:
|
||||||
|
|
||||||
One of the most powerful parts about Payload is its ability for you to define field-level hooks that can control the logic of your fields to a fine-grained level. for more information about how to define field hooks, [click here](/docs/hooks/overview#field-hooks).
|
```ts
|
||||||
|
import type { CollectionConfig } from 'payload'
|
||||||
|
|
||||||
## Field-level Access Control
|
export const Page: CollectionConfig = {
|
||||||
|
slug: 'pages',
|
||||||
|
// highlight-start
|
||||||
|
fields: [
|
||||||
|
{
|
||||||
|
name: 'field',
|
||||||
|
type: 'text',
|
||||||
|
}
|
||||||
|
]
|
||||||
|
// highlight-end
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
In addition to being able to define access control on a document-level, you can define extremely granular permissions on a field by field level. For more information about field-level access control, [click here](/docs/access-control/overview#fields).
|
<Banner type="warning">
|
||||||
|
<strong>Reminder:</strong>
|
||||||
|
Each field is an object with at least the `type` property. This matches the field to its corresponding Field Type. [More details](#field-options).
|
||||||
|
</Banner>
|
||||||
|
|
||||||
## Field Names
|
There are two main categories of fields in Payload:
|
||||||
|
|
||||||
Some fields use their `name` property as a unique identifier to store and retrieve from the database. `__v`, `salt`, and `hash` are all reserved field names which are sanitized from Payload's config and cannot be used.
|
- [Data Fields](#data-fields)
|
||||||
|
- [Presentational Fields](#presentational-fields)
|
||||||
|
|
||||||
## Default Values
|
To begin writing fields, first determine which [Field Type](#field-types) best supports your application. Then to author your field accordingly using the [Field Options](#field-options) for your chosen field type.
|
||||||
|
|
||||||
Fields can be prefilled with starting values using the `defaultValue` property. This is used in the admin UI and also on the backend as API requests will be populated with missing or undefined field values. You can assign the defaultValue directly in the field configuration or supply a function for dynamic behavior. Values assigned during a create request on the server are added before validation occurs.
|
### Data Fields
|
||||||
|
|
||||||
Functions are called with an optional argument object containing:
|
Data Fields are used to store data in the [Database](../database/overview). All Data Fields have a `name` property. This is the key that will be used to store the field's value.
|
||||||
|
|
||||||
|
Here are the available Data Fields:
|
||||||
|
|
||||||
|
- [Array](./array) - for repeating content, supports nested fields
|
||||||
|
- [Blocks](./blocks) - for block-based content, supports nested fields
|
||||||
|
- [Checkbox](./checkbox) - saves boolean true / false values
|
||||||
|
- [Code](./code) - renders a code editor interface that saves a string
|
||||||
|
- [Date](./date) - renders a date picker and saves a timestamp
|
||||||
|
- [Email](./email) - ensures the value is a properly formatted email address
|
||||||
|
- [Group](./group) - nests fields within a keyed object
|
||||||
|
- [JSON](./json) - renders a JSON editor interface that saves a JSON object
|
||||||
|
- [Number](./number) - saves numeric values
|
||||||
|
- [Point](./point) - for location data, saves geometric coordinates
|
||||||
|
- [Radio](./radio) - renders a radio button group that allows only one value to be selected
|
||||||
|
- [Relationship](./relationship) - assign relationships to other collections
|
||||||
|
- [Rich Text](./rich-text) - renders a fully extensible rich text editor
|
||||||
|
- [Select](./select) - renders a dropdown / picklist style value selector
|
||||||
|
- [Tabs (Named)](./tabs) - similar to group, but renders nested fields within a tabbed layout
|
||||||
|
- [Text](./text) - simple text input that saves a string
|
||||||
|
- [Textarea](./textarea) - similar to text, but allows for multi-line input
|
||||||
|
- [Upload](./upload) - allows local file and image upload
|
||||||
|
|
||||||
|
### Presentational Fields
|
||||||
|
|
||||||
|
Presentational Fields do not store data in the database. Instead, they are used to organize and present other fields in the [Admin Panel](../admin/overview), or to add custom UI components.
|
||||||
|
|
||||||
|
Here are the available Presentational Fields:
|
||||||
|
|
||||||
|
- [Collapsible](/docs/fields/collapsible) - nests fields within a collapsible component
|
||||||
|
- [Row](/docs/fields/row) - aligns fields horizontally
|
||||||
|
- [Tabs (Unnamed)](/docs/fields/tabs) - nests fields within a tabbed layout
|
||||||
|
- [UI](/docs/fields/ui) - blank field for custom UI components
|
||||||
|
|
||||||
|
<Banner type="warning">
|
||||||
|
<strong>Tip:</strong>
|
||||||
|
Don't see a Field Type that fits your needs? You can build your own using a [Custom Field Component](../admin/fields#the-field-component).
|
||||||
|
</Banner>
|
||||||
|
|
||||||
|
## Field Options
|
||||||
|
|
||||||
|
All fields require at least the `type` property. This matches the field to its corresponding [Field Type](#field-types) to determine its appearance and behavior within the [Admin Panel](../admin/overview). Each Field Type has its own unique set of options based on its own type.
|
||||||
|
|
||||||
|
To set a field's type, use the `type` property in your Field Config:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text', // highlight-line
|
||||||
|
name: 'myField',
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<Banner type="warning">
|
||||||
|
For a full list of configuration options, see the documentation for each [Field Type](#field-types).
|
||||||
|
</Banner>
|
||||||
|
|
||||||
|
### Field Names
|
||||||
|
|
||||||
|
All [Data Fields](#data-fields) require a `name` property. This is the key that will be used to store and retrieve the field's value in the database. This property must be unique within the Collection, Global, or nested group that it is defined in.
|
||||||
|
|
||||||
|
To set a field's name, use the `name` property in your Field Config:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField', // highlight-line
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Payload reserves various field names for internal use. Using reserved field names will result in your field being sanitized from the config.
|
||||||
|
|
||||||
|
The following field names are forbidden and cannot be used:
|
||||||
|
|
||||||
|
- `__v`
|
||||||
|
- `salt`
|
||||||
|
- `hash`
|
||||||
|
|
||||||
|
### Field-level Hooks
|
||||||
|
|
||||||
|
In addition to being able to define [Hooks](../hooks/overview) on a document-level, you can define extremely granular logic field-by-field.
|
||||||
|
|
||||||
|
To define Field-level Hooks, use the `hooks` property in your Field Config:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField',
|
||||||
|
// highlight-start
|
||||||
|
hooks: {
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
// highlight-end
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For full details on Field-level Hooks, see the [Field Hooks](../hooks/fields) documentation.
|
||||||
|
|
||||||
|
### Field-level Access Control
|
||||||
|
|
||||||
|
In addition to being able to define [Access Control](../access-control/overview) on a document-level, you can define extremely granular permissions field-by-field.
|
||||||
|
|
||||||
|
To define Field-level Access Control, use the `access` property in your Field Config:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField',
|
||||||
|
// highlight-start
|
||||||
|
access: {
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
// highlight-end
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For full details on Field-level Access Control, see the [Field Access Control](../access-control/fields) documentation.
|
||||||
|
|
||||||
|
### Default Values
|
||||||
|
|
||||||
|
Fields can be optionally prefilled with initial values. This is used in both the [Admin Panel](../admin/overview) as well as API requests to populate missing or undefined field values during the `create` or `update` operations.
|
||||||
|
|
||||||
|
To set a field's default value, use the `defaultValue` property in your Field Config:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField',
|
||||||
|
defaultValue: 'Hello, World!', // highlight-line
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Default values can be defined as a static string or a function that returns a string. Functions are called with the following arguments:
|
||||||
|
|
||||||
- `user` - the authenticated user object
|
- `user` - the authenticated user object
|
||||||
- `locale` - the currently selected locale string
|
- `locale` - the currently selected locale string
|
||||||
|
|
||||||
Here is an example of a defaultValue function that uses both:
|
Here is an example of a `defaultValue` function:
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
const translation: {
|
const translation: {
|
||||||
en: 'Written by'
|
en: 'Written by'
|
||||||
es: 'Escrito por'
|
es: 'Escrito por'
|
||||||
}
|
}
|
||||||
|
|
||||||
const field = {
|
export const myField: Field = {
|
||||||
name: 'attribution',
|
name: 'attribution',
|
||||||
type: 'text',
|
type: 'text',
|
||||||
// highlight-start
|
// highlight-start
|
||||||
defaultValue: ({ user, locale }) => `${translation[locale]} ${user.name}`,
|
defaultValue: ({ user, locale }) =>
|
||||||
|
`${translation[locale]} ${user.name}`,
|
||||||
// highlight-end
|
// highlight-end
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
<Banner type="success">
|
<Banner type="success">
|
||||||
You can use async defaultValue functions to fill fields with data from API requests.
|
<strong>Tip:</strong>
|
||||||
|
You can use async `defaultValue` functions to fill fields with data from API requests.
|
||||||
</Banner>
|
</Banner>
|
||||||
|
|
||||||
## Validation
|
### Validations
|
||||||
|
|
||||||
Field validation is enforced automatically based on the field type and other properties such as `required` or `min` and `max` value constraints on certain field types. This default behavior can be replaced by providing your own validate function for any field. It will be used on both the frontend and the backend, so it should not rely on any Node-specific packages. The validation function can be either synchronous or asynchronous and expects to return either `true` or a string error message to display in both API responses and within the Admin panel.
|
Fields are automatically validated based on their [Field Type](#field-types) and other [Field Options](#field-options) such as `required` or `min` and `max` value constraints. If needed, however, field validations can be customized or entirely replaced by providing your own custom validation functions.
|
||||||
|
|
||||||
There are two arguments available to custom validation functions.
|
To set a custom field validation function, use the `validate` property in your Field Config:
|
||||||
|
|
||||||
1. The value which is currently assigned to the field
|
|
||||||
2. An optional object with dynamic properties for more complex validation having the following:
|
|
||||||
|
|
||||||
| Property | Description |
|
|
||||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
||||||
| `data` | An object containing the full collection or global document currently being edited |
|
|
||||||
| `siblingData` | An object containing document data that is scoped to only fields within the same parent of this field |
|
|
||||||
| `operation` | Will be `create` or `update` depending on the UI action or API call |
|
|
||||||
| `id` | The `id` of the current document being edited. `id` is `undefined` during the `create` operation |
|
|
||||||
| `t` | The function for translating text, [more](/docs/configuration/i18n) |
|
|
||||||
| `user` | An object containing the currently authenticated user |
|
|
||||||
| `payload` | If the `validate` function is being executed on the server, Payload will be exposed for easily running local operations. |
|
|
||||||
|
|
||||||
## Example
|
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { CollectionConfig } from 'payload/types'
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
export const Orders: CollectionConfig = {
|
export const MyField: Field = {
|
||||||
slug: 'orders',
|
type: 'text',
|
||||||
fields: [
|
name: 'myField',
|
||||||
{
|
validate: value => Boolean(value) || 'This field is required' // highlight-line
|
||||||
name: 'customerNumber',
|
|
||||||
type: 'text',
|
|
||||||
validate: async (val, { operation }) => {
|
|
||||||
if (operation !== 'create') {
|
|
||||||
// skip validation on update
|
|
||||||
return true
|
|
||||||
}
|
|
||||||
const response = await fetch(`https://your-api.com/customers/${val}`)
|
|
||||||
if (response.ok) {
|
|
||||||
return true
|
|
||||||
}
|
|
||||||
|
|
||||||
return 'The customer number provided does not match any customers within our records.'
|
|
||||||
},
|
|
||||||
},
|
|
||||||
],
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
When supplying a field `validate` function, Payload will use yours in place of the default. To make use of the default field validation in your custom logic you can import, call and return the result as needed.
|
Custom validation functions should return either `true` or a `string` representing the error message to display in API responses.
|
||||||
|
|
||||||
For example:
|
The following arguments are provided to the `validate` function:
|
||||||
|
|
||||||
|
| Argument | Description |
|
||||||
|
| -------- | --------------------------------------------------------------------------------------------- |
|
||||||
|
| `value` | The value of the field being validated. |
|
||||||
|
| `ctx` | An object with additional data and context. [More details](#validation-context) |
|
||||||
|
|
||||||
|
#### Validation Context
|
||||||
|
|
||||||
|
The `ctx` argument contains full document data, sibling field data, the current operation, and other useful information such as currently authenticated in user:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField',
|
||||||
|
// highlight-start
|
||||||
|
validate: (val, { user }) =>
|
||||||
|
Boolean(user) || 'You must be logged in to save this field',
|
||||||
|
// highlight-end
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following additional properties are provided in the `ctx` object:
|
||||||
|
|
||||||
|
| Property | Description |
|
||||||
|
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||||
|
| `data` | An object containing the full collection or global document currently being edited. |
|
||||||
|
| `siblingData` | An object containing document data that is scoped to only fields within the same parent of this field. |
|
||||||
|
| `operation` | Will be `create` or `update` depending on the UI action or API call. |
|
||||||
|
| `id` | The `id` of the current document being edited. `id` is `undefined` during the `create` operation. |
|
||||||
|
| `req` | The current HTTP request object. Contains `payload`, `user`, etc. |
|
||||||
|
|
||||||
|
#### Reusing Default Field Validations
|
||||||
|
|
||||||
|
When using custom validation functions, Payload will use yours in place of the default. However, you might want to simply augment the default validation with your own custom logic.
|
||||||
|
|
||||||
|
To reuse default field validations, call them from within your custom validation function:
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import { text } from 'payload/fields/validations'
|
import { text } from 'payload/fields/validations'
|
||||||
@@ -162,43 +286,87 @@ const field: Field = {
|
|||||||
name: 'notBad',
|
name: 'notBad',
|
||||||
type: 'text',
|
type: 'text',
|
||||||
validate: (val, args) => {
|
validate: (val, args) => {
|
||||||
if (val === 'bad') {
|
if (val === 'bad') return 'This cannot be "bad"'
|
||||||
return 'This cannot be "bad"'
|
return text(val, args) // highlight-line
|
||||||
}
|
|
||||||
// highlight-start
|
|
||||||
return text(val, args)
|
|
||||||
// highlight-end
|
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Customizable ID
|
#### Async Field Validations
|
||||||
|
|
||||||
Collections ID fields are generated automatically by default. An explicit `id` field can be declared in the `fields` array to override this behavior.
|
Custom validation functions can also be asynchronous depending on your needs. This makes it possible to make requests to external services or perform other miscellaneous asynchronous logic.
|
||||||
Users are then required to provide a custom ID value when creating a record through the Admin UI or API.
|
|
||||||
Valid ID types are `number` and `text`.
|
|
||||||
|
|
||||||
Example:
|
To write asynchronous validation functions, use the `async` keyword to define your function:
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
{
|
import type { CollectionConfig } from 'payload'
|
||||||
|
|
||||||
|
export const Orders: CollectionConfig = {
|
||||||
|
slug: 'orders',
|
||||||
fields: [
|
fields: [
|
||||||
{
|
{
|
||||||
name: 'id',
|
name: 'customerNumber',
|
||||||
|
type: 'text',
|
||||||
|
// highlight-start
|
||||||
|
validate: async (val, { operation }) => {
|
||||||
|
if (operation !== 'create') return true
|
||||||
|
const response = await fetch(`https://your-api.com/customers/${val}`)
|
||||||
|
if (response.ok) return true
|
||||||
|
return 'The customer number provided does not match any customers within our records.'
|
||||||
|
},
|
||||||
|
// highlight-end
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Admin Options
|
||||||
|
|
||||||
|
In addition to each field's base configuration, you can use the `admin` key to specify traits and properties for fields that will only effect how they are _rendered_ within the [Admin Panel](../admin/overview), such as their appearance or behavior.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { Field } from 'payload'
|
||||||
|
|
||||||
|
export const MyField: Field = {
|
||||||
|
type: 'text',
|
||||||
|
name: 'myField',
|
||||||
|
admin: { // highlight-line
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For full details on Admin Options, see the [Field Admin Options](../admin/fields) documentation.
|
||||||
|
|
||||||
|
## Custom ID Fields
|
||||||
|
|
||||||
|
All [Collections](../configuration/collections) automatically generate their own ID field. If needed, you can override this behavior by providing an explicit ID field to your config. This will force users to provide a their own ID value when creating a record.
|
||||||
|
|
||||||
|
To define a custom ID field, add a new field with the `name` property set to `id`:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { CollectionConfig } from 'payload'
|
||||||
|
|
||||||
|
export const MyCollection: CollectionConfig = {
|
||||||
|
// ...
|
||||||
|
fields: [
|
||||||
|
{
|
||||||
|
name: 'id', // highlight-line
|
||||||
type: 'number',
|
type: 'number',
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Admin Config
|
<Banner type="warning">
|
||||||
|
<strong>Reminder:</strong>
|
||||||
In addition to each field's base configuration, you can use the `admin` key to specify traits and properties for fields that will only effect how they are _rendered_ within the [Admin Panel](../admin/overview), such as their appearance or behavior. [More details](../admin/fields).
|
The Custom ID Fields can only be of type [`Number`](./number) or [`Text`](./text).
|
||||||
|
</Banner>
|
||||||
|
|
||||||
## TypeScript
|
## TypeScript
|
||||||
|
|
||||||
You can import the internal Payload `Field` type as well as other common field types as follows:
|
You can import the Payload `Field` type as well as other common types from the `payload` package. [More details](../typescript/overview).
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
import type { Field } from 'payload/types'
|
import type { Field } from 'payload'
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user