Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: custom server providers and filter components #9303

Merged
merged 8 commits into from
Nov 21, 2024
Merged
6 changes: 3 additions & 3 deletions docs/admin/components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ keywords: admin, components, custom, documentation, Content Management System, c

The Payload [Admin Panel](./overview) is designed to be as minimal and straightforward as possible to allow for easy customization and full control over the UI. In order for Payload to support this level of customization, Payload provides a pattern for you to supply your own React components through your [Payload Config](../configuration/overview).

All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default, with the exception of [Custom Providers](#custom-providers). This enables the use of the [Local API](../local-api/overview) directly on the front-end. Custom Components are available for nearly every part of the Admin Panel for extreme granularity and control.
All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default. This enables the use of the [Local API](../local-api/overview) directly on the front-end. Custom Components are available for nearly every part of the Admin Panel for extreme granularity and control.

<Banner type="success">
<strong>Note:</strong>
Expand Down Expand Up @@ -151,7 +151,7 @@ export default buildConfig({
## Building Custom Components
All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default, with the exception of [Custom Providers](#custom-providers). This enables the use of the [Local API](../local-api/overview) directly on the front-end, among other things.
All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default. This enables the use of the [Local API](../local-api/overview) directly on the front-end, among other things.
### Default Props
Expand Down Expand Up @@ -546,5 +546,5 @@ export const useMyCustomContext = () => useContext(MyCustomContext)
```

<Banner type="warning">
<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>React Context exists only within Client Components. This means they must include the `use client` directive at the top of their files and cannot contain server-only code. To use a Server Component here, simply _wrap_ your Client Component with it.
</Banner>
2 changes: 1 addition & 1 deletion docs/admin/customizing-css.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ keywords: admin, css, scss, documentation, Content Management System, cms, headl

Customizing the Payload [Admin Panel](./overview) through CSS alone is one of the easiest and most powerful ways to customize the look and feel of the dashboard. To allow for this level of customization, Payload:

1. Exposes a [root-level stylesheet](#global-css) for you to easily to inject custom selectors
1. Exposes a [root-level stylesheet](#global-css) for you to inject custom selectors
1. Provides a [CSS library](#css-library) that can be easily overridden or extended
1. Uses [BEM naming conventions](http://getbem.com) so that class names are globally accessible

Expand Down
40 changes: 32 additions & 8 deletions docs/admin/fields.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ A description can be configured in three ways:
- As a function which returns a string. [More details](#description-functions).
- As a React component. [More details](#description).

To easily add a Custom Description to a field, use the `admin.description` property in your [Field Config](../fields/overview):
To add a Custom Description to a field, use the `admin.description` property in your [Field Config](../fields/overview):

```ts
import type { SanitizedCollectionConfig } from 'payload'
Expand Down Expand Up @@ -95,7 +95,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {

Custom Descriptions can also be defined as a function. Description Functions are executed on the server and can be used to format simple descriptions based on the user's current [Locale](../configuration/localization).

To easily add a Description Function to a field, set the `admin.description` property to a _function_ in your [Field Config](../fields/overview):
To add a Description Function to a field, set the `admin.description` property to a _function_ in your [Field Config](../fields/overview):

```ts
import type { SanitizedCollectionConfig } from 'payload'
Expand Down Expand Up @@ -173,7 +173,7 @@ Within the [Admin Panel](./overview), fields are represented in three distinct p
- [Cell](#cell) - The table cell component rendered in the List View.
- [Filter](#filter) - The filter component rendered in the List View.

To easily swap in Field Components with your own, use the `admin.components` property in your [Field Config](../fields/overview):
To swap in Field Components with your own, use the `admin.components` property in your [Field Config](../fields/overview):

```ts
import type { CollectionConfig } from 'payload'
Expand Down Expand Up @@ -211,7 +211,7 @@ The following options are available:

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 in your [Field Config](../fields/overview):
To swap in your own Field Component, use the `admin.components.Field` property in your [Field Config](../fields/overview):

```ts
import type { CollectionConfig } from 'payload'
Expand Down Expand Up @@ -312,7 +312,7 @@ import type {

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 in your [Field Config](../fields/overview):
To swap in your own Cell Component, use the `admin.components.Cell` property in your [Field Config](../fields/overview):

```ts
import type { Field } from 'payload'
Expand All @@ -337,11 +337,35 @@ All Cell Components receive the same [Default Field Component Props](#field), pl

For details on how to build Custom Components themselves, see [Building Custom Components](./components#building-custom-components).

### Filter

The Filter Component is the actual input element rendered within the "Filter By" dropdown of the List View used to represent this field when building filters.

To swap in your own Filter Component, use the `admin.components.Filter` property in your [Field Config](../fields/overview):

```ts
import type { Field } from 'payload'

export const myField: Field = {
name: 'myField',
type: 'text',
admin: {
components: {
Filter: '/path/to/MyCustomFilterComponent', // highlight-line
},
},
}
```

All Custom Filter Components receive the same [Default Field Component Props](#field).

For details on how to build Custom Components themselves, see [Building Custom Components](./components#building-custom-components).

### Label

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 in your [Field Config](../fields/overview):
To swap in your own Label Component, use the `admin.components.Label` property in your [Field Config](../fields/overview):

```ts
import type { Field } from 'payload'
Expand Down Expand Up @@ -377,7 +401,7 @@ import type {

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 in your [Field Config](../fields/overview):
To add a Description Component to a field, use the `admin.components.Description` property in your [Field Config](../fields/overview):

```ts
import type { SanitizedCollectionConfig } from 'payload'
Expand Down Expand Up @@ -419,7 +443,7 @@ import type {

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 in your [Field Config](../fields/overview):
To swap in your own Error Component, use the `admin.components.Error` property in your [Field Config](../fields/overview):

```ts
import type { Field } from 'payload'
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/hooks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -785,7 +785,7 @@ const Greeting: React.FC = () => {

## useConfig

Used to easily retrieve the Payload [Client Config](./components#accessing-the-payload-config).
Used to retrieve the Payload [Client Config](./components#accessing-the-payload-config).

```tsx
'use client'
Expand Down
8 changes: 4 additions & 4 deletions docs/admin/views.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ To swap in your own Custom View, first consult the list of available components,

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.

To easily swap Root Views with your own, or to [create entirely new ones](#adding-new-root-views), use the `admin.components.views` property of your root [Payload Config](../configuration/overview):
To swap Root Views with your own, or to [create entirely new ones](#adding-new-root-views), use the `admin.components.views` property of your root [Payload Config](../configuration/overview):

```ts
import { buildConfig } from 'payload'
Expand Down Expand Up @@ -143,7 +143,7 @@ The above example shows how to add a new [Root View](#root-views), but the patte

Collection Views are views that are scoped under the `/collections` route, such as the Collection List and Document Edit views.

To easily swap out Collection Views with your own, or to [create entirely new ones](#adding-new-views), use the `admin.components.views` property of your [Collection Config](../collections/overview):
To swap out Collection Views with your own, or to [create entirely new ones](#adding-new-views), use the `admin.components.views` property of your [Collection Config](../collections/overview):

```ts
import type { SanitizedCollectionConfig } from 'payload'
Expand Down Expand Up @@ -198,7 +198,7 @@ The following options are available:

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 in your [Global Config](../globals/overview):
To 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
import type { SanitizedGlobalConfig } from 'payload'
Expand Down Expand Up @@ -248,7 +248,7 @@ The following options are available:

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 in your [Collection Config](../collections/overview) or [Global Config](../globals/overview):
To 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
import type { SanitizedCollectionConfig } from 'payload'
Expand Down
4 changes: 2 additions & 2 deletions docs/migration-guide/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -656,8 +656,8 @@ For more details, see the [Documentation](https://payloadcms.com/docs/getting-st
+ edit: {
+ tab: {
+ isActive: ({ href }) => true,
+ href: ({ href }) => ''
+ Component: './path/to/CustomComponent.tsx', // Or use a Custom Component
+ href: ({ href }) => '' // or use a Custom Component (see below)
+ // Component: './path/to/CustomComponent.tsx'
+ }
+ },
},
Expand Down