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: clarifies custom providers and adds custom field filter components #9303

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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>
8 changes: 4 additions & 4 deletions 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 Expand Up @@ -62,13 +62,13 @@ You can also override Payload's built-in [CSS Variables](https://developer.mozil

The following variables are defined and can be overridden:

- [Breakpoints](https://github.com/payloadcms/payload/blob/beta/packages/ui/src/scss/queries.scss)
- [Colors](https://github.com/payloadcms/payload/blob/beta/packages/ui/src/scss/colors.scss)
- [Breakpoints](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/queries.scss)
- [Colors](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/colors.scss)
- Base color shades (white to black by default)
- Success / warning / error color shades
- Theme-specific colors (background, input background, text color, etc.)
- Elevation colors (used to determine how "bright" something should be when compared to the background)
- [Sizing](https://github.com/payloadcms/payload/blob/beta/packages/ui/src/scss/app.scss)
- [Sizing](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/app.scss)
- Horizontal gutter
- Transition speeds
- Font sizes
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
2 changes: 1 addition & 1 deletion docs/admin/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ The following options are available:

## I18n

The Payload Admin Panel is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/beta/packages/translations). Languages are automatically detected based on the user's browser and used by the Admin Panel to display all text in that language. If no language was detected, or if the user's language is not yet supported, English will be chosen. Users can easily specify their language by selecting one from their account page. See [I18n](../configuration/i18n) for more information.
The Payload Admin Panel is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/main/packages/translations). Languages are automatically detected based on the user's browser and used by the Admin Panel to display all text in that language. If no language was detected, or if the user's language is not yet supported, English will be chosen. Users can easily specify their language by selecting one from their account page. See [I18n](../configuration/i18n) for more information.

## Light and Dark Modes

Expand Down
28 changes: 14 additions & 14 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 All @@ -32,7 +32,7 @@ const config = buildConfig({
components: {
views: {
customView: {
Component: '/path/to/MyCustomView#MyCustomView', // highlight-line
Component: '/path/to/MyCustomView.tsx#MyCustomView', // highlight-line
path: '/my-custom-view',
}
},
Expand Down Expand Up @@ -113,7 +113,7 @@ const config = buildConfig({
// highlight-start
myCustomView: {
// highlight-end
Component: '/path/to/MyCustomView#MyCustomViewComponent',
Component: '/path/to/MyCustomView.tsx#MyCustomViewComponent',
path: '/my-custom-view',
},
},
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 All @@ -155,7 +155,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
views: {
edit: {
root: {
Component: '/path/to/MyCustomEditView', // highlight-line
Component: '/path/to/MyCustomEditView.tsx', // highlight-line
}
// other options include:
// default
Expand All @@ -167,7 +167,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
// See "Document Views" for more details
},
list: {
Component: '/path/to/MyCustomListView',
Component: '/path/to/MyCustomListView.tsx',
}
},
},
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 All @@ -210,7 +210,7 @@ export const MyGlobalConfig: SanitizedGlobalConfig = {
views: {
edit: {
root: {
Component: '/path/to/MyCustomEditView', // highlight-line
Component: '/path/to/MyCustomEditView.tsx', // highlight-line
}
// other options include:
// default
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 All @@ -260,7 +260,7 @@ export const MyCollectionOrGlobalConfig: SanitizedCollectionConfig = {
views: {
edit: {
api: {
Component: '/path/to/MyCustomAPIViewComponent', // highlight-line
Component: '/path/to/MyCustomAPIViewComponent.tsx', // highlight-line
},
},
},
Expand Down Expand Up @@ -301,14 +301,14 @@ export const MyCollection: SanitizedCollectionConfig = {
views: {
edit: {
myCustomTab: {
Component: '/path/to/MyCustomTab',
Component: '/path/to/MyCustomTab.tsx',
path: '/my-custom-tab',
tab: {
Component: '/path/to/MyCustomTabComponent' // highlight-line
Component: '/path/to/MyCustomTabComponent.tsx' // highlight-line
}
},
anotherCustomTab: {
Component: '/path/to/AnotherCustomView',
Component: '/path/to/AnotherCustomView.tsx',
path: '/another-custom-view',
// highlight-start
tab: {
Expand Down Expand Up @@ -342,7 +342,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
components: {
views: {
edit: {
Component: '/path/to/MyCustomView' // highlight-line
Component: '/path/to/MyCustomView.tsx' // highlight-line
}
},
},
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration/i18n.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ desc: Manage and customize internationalization support in your CMS editor exper
keywords: internationalization, i18n, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---

The [Admin Panel](../admin/overview) is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/beta/packages/translations). With I18n, editors can navigate the interface and read API error messages in their preferred language. This is similar to [Localization](./localization), but instead of managing translations for the data itself, you are managing translations for your application's interface.
The [Admin Panel](../admin/overview) is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/main/packages/translations). With I18n, editors can navigate the interface and read API error messages in their preferred language. This is similar to [Localization](./localization), but instead of managing translations for the data itself, you are managing translations for your application's interface.

By default, Payload comes with preinstalled with English, but you can easily load other languages into your own application. Languages are automatically detected based on the request. If no language was detected, or if the user's language is not yet supported by your application, English will be chosen.

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ To install a Database Adapter, you can run **one** of the following commands:

#### 2. Copy Payload files into your Next.js app folder

Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the [Blank Template](https://github.com/payloadcms/payload/tree/beta/templates/blank/src/app/(payload)) on GitHub. Once you have the required Payload files in place in your `/app` folder, you should have something like this:
Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the [Blank Template](https://github.com/payloadcms/payload/tree/main/templates/blank/src/app/(payload)) on GitHub. Once you have the required Payload files in place in your `/app` folder, you should have something like this:

```plaintext
app/
Expand Down
Loading
Loading