From e5b3da972f67a24cb1daa61cca89862ea0c1b5b7 Mon Sep 17 00:00:00 2001 From: Jacob Fletcher Date: Thu, 23 Jan 2025 01:54:31 -0500 Subject: [PATCH] docs: moves collection and globals admin docs to their respective config overviews (#10743) Similar to #10742. Collection and global-level admin options are currently documented within the "admin > collections" and "admin > globals" pages, respectively. This makes them hard to find because users, myself included, intuitively navigate to the collection and global overview docs to locate this information before realizing it lives elsewhere. Now, they are rendered within "configuration > collections" and "configuration > globals" as expected and the old pages have been removed altogether. --- docs/admin/collections.mdx | 183 ----------------------------- docs/admin/components.mdx | 8 +- docs/admin/globals.mdx | 107 ----------------- docs/admin/metadata.mdx | 2 +- docs/admin/overview.mdx | 2 +- docs/admin/views.mdx | 4 +- docs/configuration/collections.mdx | 178 +++++++++++++++++++++++++++- docs/configuration/globals.mdx | 106 ++++++++++++++++- docs/configuration/overview.mdx | 2 +- docs/fields/overview.mdx | 32 ++--- docs/live-preview/overview.mdx | 8 +- 11 files changed, 305 insertions(+), 327 deletions(-) delete mode 100644 docs/admin/collections.mdx delete mode 100644 docs/admin/globals.mdx diff --git a/docs/admin/collections.mdx b/docs/admin/collections.mdx deleted file mode 100644 index 88a394c09..000000000 --- a/docs/admin/collections.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Collection Admin Config -label: Collections -order: 20 -desc: -keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs ---- - -The behavior of [Collections](../configuration/collections) within the [Admin Panel](./overview) can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding [Custom Components](./components), selecting which fields to display in the List View, and more. - -To configure Admin Options for Collections, use the `admin` property in your Collection Config: - -```ts -import type { CollectionConfig } from 'payload' - -export const MyCollection: CollectionConfig = { - // ... - admin: { // highlight-line - // ... - }, -} -``` - -## Admin Options - -The following options are available: - -| Option | Description | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`group`** | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. | -| **`hidden`** | Set to true or a function, called with the current user, returning true to exclude this Collection from navigation and admin routing. | -| **`hooks`** | Admin-specific hooks for this Collection. [More details](../hooks/collections). | -| **`useAsTitle`** | Specify a top-level field to use for a document title throughout the Admin Panel. If no field is defined, the ID of the document is used as the title. A field with `virtual: true` cannot be used as the title. | -| **`description`** | Text to display below the Collection label in the List View to give editors more information. Alternatively, you can use the `admin.components.Description` to render a React component. [More details](#custom-components). | -| **`defaultColumns`** | Array of field names that correspond to which columns to show by default in this Collection's List View. | -| **`hideAPIURL`** | Hides the "API URL" meta field while editing documents within this Collection. | -| **`enableRichTextLink`** | The [Rich Text](../fields/rich-text) field features a `Link` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default. | -| **`enableRichTextRelationship`** | The [Rich Text](../fields/rich-text) field features a `Relationship` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default. | -| **`meta`** | Page metadata overrides to apply to this Collection within the Admin Panel. [More details](./metadata). | -| **`preview`** | Function to generate preview URLs within the Admin Panel that can point to your app. [More details](#preview). | -| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). | -| **`components`** | Swap in your own React components to be used within this Collection. [More details](#custom-components). | -| **`listSearchableFields`** | Specify which fields should be searched in the List search view. [More details](#list-searchable-fields). | -| **`pagination`** | Set pagination-specific options for this Collection. [More details](#pagination). | -| **`baseListFilter`** | You can define a default base filter for this collection's List view, which will be merged into any filters that the user performs. | - -### Custom Components - -Collections can set their own [Custom Components](./components) which only apply to [Collection](../configuration/collections)-specific UI within the [Admin Panel](./overview). This includes elements such as the Save Button, or entire layouts such as the Edit View. - -To override Collection Components, use the `admin.components` property in your [Collection Config](../configuration/collections): - -```ts -import type { SanitizedCollectionConfig } from 'payload' - -export const MyCollection: SanitizedCollectionConfig = { - // ... - admin: { - components: { // highlight-line - // ... - }, - }, -} -``` - -The following options are available: - -| Path | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **`beforeList`** | An array of components to inject _before_ the built-in List View | -| **`beforeListTable`** | An array of components to inject _before_ the built-in List View's table | -| **`afterList`** | An array of components to inject _after_ the built-in List View | -| **`afterListTable`** | An array of components to inject _after_ the built-in List View's table | -| **`Description`** | A component to render below the Collection label in the List View. An alternative to the `admin.description` property. | -| **`edit.SaveButton`** | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled. | -| **`edit.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. | -| **`edit.PublishButton`** | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. | -| **`edit.PreviewButton`** | Replace the default Preview Button with a Custom Component. [Preview](#preview) must be enabled. | -| **`edit.Upload`** | Replace the default Upload component with a Custom Component. [Upload](../upload/overview) must be enabled. | -| **`views`** | Override or create new views within the Admin Panel. [More details](./views). | - - - **Note:** - For details on how to build Custom Components, see [Building Custom Components](./components#building-custom-components). - - -### Preview - -It is possible to display a Preview Button within the Edit View of the Admin Panel. This will allow editors to visit the frontend of your app the corresponds to the document they are actively editing. This way they can preview the latest, potentially unpublished changes. - -To configure the Preview Button, set the `admin.preview` property to a function in your [Collection Config](../configuration/collections): - -```ts -import type { CollectionConfig } from 'payload' - -export const Posts: CollectionConfig = { - // ... - admin: { - // highlight-start - preview: (doc, { locale }) => { - if (doc?.slug) { - return `/${doc.slug}?locale=${locale}` - } - - return null - }, - // highlight-end - }, -} -``` - -The `preview` property resolves to a string that points to your front-end application with additional URL parameters. This can be an absolute URL or a relative path. - -The preview function receives two arguments: - -| Argument | Description | -| --- | --- | -| **`doc`** | The Document being edited. | -| **`ctx`** | An object containing `locale`, `token`, and `req` properties. The `token` is the currently logged-in user's JWT. | - -If your application requires a fully qualified URL, such as within deploying to Vercel Preview Deployments, you can use the `req` property to build this URL: - -```ts -preview: (doc, { req }) => `${req.protocol}//${req.host}/${doc.slug}` // highlight-line -``` - - - **Note:** - For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples). - - -### Pagination - -All Collections receive their own List View which displays a paginated list of documents that can be sorted and filtered. The pagination behavior of the List View can be customized on a per-Collection basis, and uses the same [Pagination](../queries/pagination) API that Payload provides. - -To configure pagination options, use the `admin.pagination` property in your [Collection Config](../configuration/collections): - -```ts -import type { CollectionConfig } from 'payload' - -export const Posts: CollectionConfig = { - // ... - admin: { - // highlight-start - pagination: { - defaultLimit: 10, - limits: [10, 20, 50], - }, - // highlight-end - }, -} -``` - -The following options are available: - -| Option | Description | -| -------------- | --------------------------------------------------------------------------------------------------- | -| `defaultLimit` | Integer that specifies the default per-page limit that should be used. Defaults to 10. | -| `limits` | Provide an array of integers to use as per-page options for admins to choose from in the List View. | - -### List Searchable Fields - -In the List View, there is a "search" box that allows you to quickly find a document through a simple text search. By default, it searches on the ID field. If defined, the `admin.useAsTitle` field is used. Or, you can explicitly define which fields to search based on the needs of your application. - -To define which fields should be searched, use the `admin.listSearchableFields` property in your [Collection Config](../configuration/collections): - -```ts -import type { CollectionConfig } from 'payload' - -export const Posts: CollectionConfig = { - // ... - admin: { - // highlight-start - listSearchableFields: ['title', 'slug'], - // highlight-end - }, -} -``` - - - **Tip:** - If you are adding `listSearchableFields`, make sure you index each of these fields so your admin queries can remain performant. - diff --git a/docs/admin/components.mdx b/docs/admin/components.mdx index 63d7c43c4..875e10578 100644 --- a/docs/admin/components.mdx +++ b/docs/admin/components.mdx @@ -18,8 +18,8 @@ All Custom Components in Payload are [React Server Components](https://react.dev There are four main types of Custom Components in Payload: - [Root Components](#root-components) -- [Collection Components](./collections#custom-components) -- [Global Components](./globals#custom-components) +- [Collection Components](../configuration/collections/#custom-components) +- [Global Components](../configuration/globals#custom-components) - [Field Components](../fields/overview#custom-components) To swap in your own Custom Component, first 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. @@ -185,7 +185,7 @@ Each Custom Component receives the following props by default: **Reminder:** - All Custom Components also receive various other props that are specific component being rendered. See [Root Components](#root-components), [Collection Components](./collections#custom-components), [Global Components](./globals#custom-components), or [Field Components](../fields/overview#custom-components) for a complete list of all default props per component. + All Custom Components also receive various other props that are specific component being rendered. See [Root Components](#root-components), [Collection Components](../configuration/collections#custom-components), [Global Components](../configuraiton/globals#custom-components), or [Field Components](../fields/overview#custom-components) for a complete list of all default props per component. ### Custom Props @@ -504,7 +504,7 @@ The following options are available: **Note:** - You can also use set [Collection Components](./collections#custom-components) and [Global Components](./globals#custom-components) in their respective configs. + You can also use set [Collection Components](../configuration/collections#custom-components) and [Global Components](../configuration/globals#custom-components) in their respective configs. ### Custom Providers diff --git a/docs/admin/globals.mdx b/docs/admin/globals.mdx deleted file mode 100644 index b95d9f87d..000000000 --- a/docs/admin/globals.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Global Admin Config -label: Globals -order: 30 -desc: -keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs ---- - -The behavior of [Globals](../configuration/globals) within the [Admin Panel](./overview) can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding [Custom Components](./components), setting page metadata, and more. - -To configure Admin Options for Globals, use the `admin` property in your Global Config: - -```ts -import { GlobalConfig } from 'payload' - -export const MyGlobal: GlobalConfig = { - // ... - admin: { // highlight-line - // ... - }, -} -``` - -## Admin Options - -The following options are available: - -| Option | Description | -| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **`group`** | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. | -| **`hidden`** | Set to true or a function, called with the current user, returning true to exclude this Global from navigation and admin routing. | -| **`components`** | Swap in your own React components to be used within this Global. [More details](#custom-components). | -| **`preview`** | Function to generate a preview URL within the Admin Panel for this Global that can point to your app. [More details](#preview). | -| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). | -| **`hideAPIURL`** | Hides the "API URL" meta field while editing documents within this collection. | -| **`meta`** | Page metadata overrides to apply to this Global within the Admin Panel. [More details](./metadata). | - -### Custom Components - -Globals can set their own [Custom Components](./components) which only apply to [Global](../configuration/globals)-specific UI within the [Admin Panel](./overview). This includes elements such as the Save Button, or entire layouts such as the Edit View. - -To override Global Components, use the `admin.components` property in your [Global Config](../configuration/globals): - -```ts -import type { SanitizedGlobalConfig } from 'payload' - -export const MyGlobal: SanitizedGlobalConfig = { - // ... - admin: { - components: { // highlight-line - // ... - }, - }, -} -``` - -The following options are available: - -| Path | Description | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| **`elements.SaveButton`** | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled. | -| **`elements.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. | -| **`elements.PublishButton`** | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. | -| **`elements.PreviewButton`** | Replace the default Preview Button with a Custom Component. [Preview](#preview) must be enabled. | -| **`views`** | Override or create new views within the Admin Panel. [More details](./views). | - - - **Note:** - For details on how to build Custom Components, see [Building Custom Components](./components#building-custom-components). - - -### Preview - -It is possible to display a Preview Button within the Edit View of the Admin Panel. This will allow editors to visit the frontend of your app the corresponds to the document they are actively editing. This way they can preview the latest, potentially unpublished changes. - -To configure the Preview Button, set the `admin.preview` property to a function in your Global Config: - -```ts -import { GlobalConfig } from 'payload' - -export const MainMenu: GlobalConfig = { - // ... - admin: { - // highlight-start - preview: (doc, { locale }) => { - if (doc?.slug) { - return `/${doc.slug}?locale=${locale}` - } - - return null - }, - // highlight-end - }, -} -``` - -The preview function receives two arguments: - -| Argument | Description | -| --- | --- | -| **`doc`** | The Document being edited. | -| **`ctx`** | An object containing `locale` and `token` properties. The `token` is the currently logged-in user's JWT. | - - - **Note:** - For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples). - diff --git a/docs/admin/metadata.mdx b/docs/admin/metadata.mdx index 4f15a1eff..fdb27241d 100644 --- a/docs/admin/metadata.mdx +++ b/docs/admin/metadata.mdx @@ -58,7 +58,7 @@ The following options are available for Root Metadata: **Reminder:** - These are the _root-level_ options for the Admin Panel. You can also customize [Collection Metadata](./collections), [Global Metadata](./globals), and [Document Metadata](./documents) in their respective configs. + These are the _root-level_ options for the Admin Panel. You can also customize metadata on the [Collection](../configuration/collections), [Global](../configuration/globals), and Document levels through their respective configs. ### Icons diff --git a/docs/admin/overview.mdx b/docs/admin/overview.mdx index e889b04e8..e18c673f1 100644 --- a/docs/admin/overview.mdx +++ b/docs/admin/overview.mdx @@ -103,7 +103,7 @@ The following options are available: **Reminder:** - These are the _root-level_ options for the Admin Panel. You can also customize [Collection Admin Options](./collections) and [Global Admin Options](./globals) through their respective `admin` keys. + These are the _root-level_ options for the Admin Panel. You can also customize [Collection Admin Options](../configuration/collections#admin-options) and [Global Admin Options](../configuration/globals#admin-options) through their respective `admin` keys. ### The Admin User Collection diff --git a/docs/admin/views.mdx b/docs/admin/views.mdx index 23d4e4c4c..25d3bfdec 100644 --- a/docs/admin/views.mdx +++ b/docs/admin/views.mdx @@ -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 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](../configuration/collections): ```ts import type { SanitizedCollectionConfig } from 'payload' @@ -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 swap out Document Views with your own, or to [create entirely new ones](#adding-new-views), use the `admin.components.views.Edit[key]` property in your [Collection Config](../collections/overview) or [Global Config](../configuration/globals): +To swap out Document Views with your own, or to [create entirely new ones](#adding-new-views), use the `admin.components.views.Edit[key]` property in your [Collection Config](../configuration/collections) or [Global Config](../configuration/globals): ```ts import type { SanitizedCollectionConfig } from 'payload' diff --git a/docs/configuration/collections.mdx b/docs/configuration/collections.mdx index a8699f389..8293eb544 100644 --- a/docs/configuration/collections.mdx +++ b/docs/configuration/collections.mdx @@ -59,7 +59,7 @@ The following options are available: | Option | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/collections). | +| **`admin`** | The configuration options for the Admin Panel. [More details](#admin-options). | | **`access`** | Provide Access Control functions to define exactly who should be able to do what with Documents in this Collection. [More details](../access-control/collections). | | **`auth`** | Specify options if you would like this Collection to feature authentication. [More details](../authentication/overview). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | @@ -93,9 +93,181 @@ Fields define the schema of the Documents within a Collection. To learn more, go [Collection Hooks](../hooks/collections) allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation. -### Admin Options +## Admin Options -You can customize the way that the [Admin Panel](../admin/overview) behaves on a Collection-by-Collection basis. To learn more, go to the [Collection Admin Options](../admin/collections) documentation. +The behavior of Collections within the [Admin Panel](../admin/overview) can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding [Custom Components](./components), selecting which fields to display in the List View, and more. + +To configure Admin Options for Collections, use the `admin` property in your Collection Config: + +```ts +import type { CollectionConfig } from 'payload' + +export const MyCollection: CollectionConfig = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The following options are available: + +| Option | Description | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`group`** | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. | +| **`hidden`** | Set to true or a function, called with the current user, returning true to exclude this Collection from navigation and admin routing. | +| **`hooks`** | Admin-specific hooks for this Collection. [More details](../hooks/collections). | +| **`useAsTitle`** | Specify a top-level field to use for a document title throughout the Admin Panel. If no field is defined, the ID of the document is used as the title. A field with `virtual: true` cannot be used as the title. | +| **`description`** | Text to display below the Collection label in the List View to give editors more information. Alternatively, you can use the `admin.components.Description` to render a React component. [More details](#custom-components). | +| **`defaultColumns`** | Array of field names that correspond to which columns to show by default in this Collection's List View. | +| **`hideAPIURL`** | Hides the "API URL" meta field while editing documents within this Collection. | +| **`enableRichTextLink`** | The [Rich Text](../fields/rich-text) field features a `Link` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default. | +| **`enableRichTextRelationship`** | The [Rich Text](../fields/rich-text) field features a `Relationship` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default. | +| **`meta`** | Page metadata overrides to apply to this Collection within the Admin Panel. [More details](../admin/metadata). | +| **`preview`** | Function to generate preview URLs within the Admin Panel that can point to your app. [More details](#preview). | +| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). | +| **`components`** | Swap in your own React components to be used within this Collection. [More details](#custom-components). | +| **`listSearchableFields`** | Specify which fields should be searched in the List search view. [More details](#list-searchable-fields). | +| **`pagination`** | Set pagination-specific options for this Collection. [More details](#pagination). | +| **`baseListFilter`** | You can define a default base filter for this collection's List view, which will be merged into any filters that the user performs. | + +### Custom Components + +Collections can set their own [Custom Components](../admin/components) which only apply to Collection-specific UI within the [Admin Panel](../admin/overview). This includes elements such as the Save Button, or entire layouts such as the Edit View. + +To override Collection Components, use the `admin.components` property in your Collection Config: + +```ts +import type { SanitizedCollectionConfig } from 'payload' + +export const MyCollection: SanitizedCollectionConfig = { + // ... + admin: { + components: { // highlight-line + // ... + }, + }, +} +``` + +The following options are available: + +| Path | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| **`beforeList`** | An array of components to inject _before_ the built-in List View | +| **`beforeListTable`** | An array of components to inject _before_ the built-in List View's table | +| **`afterList`** | An array of components to inject _after_ the built-in List View | +| **`afterListTable`** | An array of components to inject _after_ the built-in List View's table | +| **`Description`** | A component to render below the Collection label in the List View. An alternative to the `admin.description` property. | +| **`edit.SaveButton`** | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled. | +| **`edit.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. | +| **`edit.PublishButton`** | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. | +| **`edit.PreviewButton`** | Replace the default Preview Button with a Custom Component. [Preview](#preview) must be enabled. | +| **`edit.Upload`** | Replace the default Upload component with a Custom Component. [Upload](../upload/overview) must be enabled. | +| **`views`** | Override or create new views within the Admin Panel. [More details](../admin/views). | + + + **Note:** + For details on how to build Custom Components, see [Building Custom Components](../admin/components#building-custom-components). + + +### Preview + +It is possible to display a Preview Button within the Edit View of the Admin Panel. This will allow editors to visit the frontend of your app the corresponds to the document they are actively editing. This way they can preview the latest, potentially unpublished changes. + +To configure the Preview Button, set the `admin.preview` property to a function in your Collection Config: + +```ts +import type { CollectionConfig } from 'payload' + +export const Posts: CollectionConfig = { + // ... + admin: { + // highlight-start + preview: (doc, { locale }) => { + if (doc?.slug) { + return `/${doc.slug}?locale=${locale}` + } + + return null + }, + // highlight-end + }, +} +``` + +The `preview` property resolves to a string that points to your front-end application with additional URL parameters. This can be an absolute URL or a relative path. + +The preview function receives two arguments: + +| Argument | Description | +| --- | --- | +| **`doc`** | The Document being edited. | +| **`ctx`** | An object containing `locale`, `token`, and `req` properties. The `token` is the currently logged-in user's JWT. | + +If your application requires a fully qualified URL, such as within deploying to Vercel Preview Deployments, you can use the `req` property to build this URL: + +```ts +preview: (doc, { req }) => `${req.protocol}//${req.host}/${doc.slug}` // highlight-line +``` + + + **Note:** + For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples). + + +### Pagination + +All Collections receive their own List View which displays a paginated list of documents that can be sorted and filtered. The pagination behavior of the List View can be customized on a per-Collection basis, and uses the same [Pagination](../queries/pagination) API that Payload provides. + +To configure pagination options, use the `admin.pagination` property in your Collection Config: + +```ts +import type { CollectionConfig } from 'payload' + +export const Posts: CollectionConfig = { + // ... + admin: { + // highlight-start + pagination: { + defaultLimit: 10, + limits: [10, 20, 50], + }, + // highlight-end + }, +} +``` + +The following options are available: + +| Option | Description | +| -------------- | --------------------------------------------------------------------------------------------------- | +| `defaultLimit` | Integer that specifies the default per-page limit that should be used. Defaults to 10. | +| `limits` | Provide an array of integers to use as per-page options for admins to choose from in the List View. | + +### List Searchable Fields + +In the List View, there is a "search" box that allows you to quickly find a document through a simple text search. By default, it searches on the ID field. If defined, the `admin.useAsTitle` field is used. Or, you can explicitly define which fields to search based on the needs of your application. + +To define which fields should be searched, use the `admin.listSearchableFields` property in your Collection Config: + +```ts +import type { CollectionConfig } from 'payload' + +export const Posts: CollectionConfig = { + // ... + admin: { + // highlight-start + listSearchableFields: ['title', 'slug'], + // highlight-end + }, +} +``` + + + **Tip:** + If you are adding `listSearchableFields`, make sure you index each of these fields so your admin queries can remain performant. + ## GraphQL diff --git a/docs/configuration/globals.mdx b/docs/configuration/globals.mdx index 7fde9cf60..94ed8c11d 100644 --- a/docs/configuration/globals.mdx +++ b/docs/configuration/globals.mdx @@ -6,7 +6,7 @@ desc: Set up your Global config for your needs by defining fields, adding slugs keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- -Globals are in many ways similar to [Collections](../configuration/collections), except that they correspond to only a single Document. You can define as many Globals as your application needs. Each Global Document is stored in the [Database](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates a [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) used to manage your Documents. +Globals are in many ways similar to [Collections](./collections), except that they correspond to only a single Document. You can define as many Globals as your application needs. Each Global Document is stored in the [Database](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates a [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) used to manage your Documents. Globals are the primary way to structure singletons in Payload, such as a header navigation, site-wide banner alerts, or app-wide localized strings. Each Global can have its own unique [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more. @@ -25,7 +25,7 @@ export default buildConfig({ **Tip:** - If you have more than one Global that share the same structure, consider using a [Collection](../configuration/collections) instead. + If you have more than one Global that share the same structure, consider using a [Collection](./collections) instead. ## Config Options @@ -68,7 +68,7 @@ The following options are available: | Option | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`access`** | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals). | -| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/globals). | +| **`admin`** | The configuration options for the Admin Panel. [More details](#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`dbName`** | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. | | **`description`** | Text or React component to display below the Global header to give editors more information. | @@ -96,9 +96,105 @@ Fields define the schema of the Global. To learn more, go to the [Fields](../fie [Global Hooks](../hooks/globals) allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation. -### Admin Options +## Admin Options -You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis. To learn more, go to the [Global Admin Options](../admin/globals) documentation. +The behavior of Globals within the [Admin Panel](../admin/overview) can be fully customized to fit the needs of your application. This includes grouping or hiding their navigation links, adding [Custom Components](../admin/components), setting page metadata, and more. + +To configure Admin Options for Globals, use the `admin` property in your Global Config: + +```ts +import { GlobalConfig } from 'payload' + +export const MyGlobal: GlobalConfig = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +The following options are available: + +| Option | Description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **`group`** | Text or localization object used to group Collection and Global links in the admin navigation. Set to `false` to hide the link from the navigation while keeping its routes accessible. | +| **`hidden`** | Set to true or a function, called with the current user, returning true to exclude this Global from navigation and admin routing. | +| **`components`** | Swap in your own React components to be used within this Global. [More details](#custom-components). | +| **`preview`** | Function to generate a preview URL within the Admin Panel for this Global that can point to your app. [More details](#preview). | +| **`livePreview`** | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview). | +| **`hideAPIURL`** | Hides the "API URL" meta field while editing documents within this collection. | +| **`meta`** | Page metadata overrides to apply to this Global within the Admin Panel. [More details](../admin/metadata). | + +### Custom Components + +Globals can set their own [Custom Components](../admin/components) which only apply to Global-specific UI within the [Admin Panel](../admin/overview). This includes elements such as the Save Button, or entire layouts such as the Edit View. + +To override Global Components, use the `admin.components` property in your Global Config: + +```ts +import type { SanitizedGlobalConfig } from 'payload' + +export const MyGlobal: SanitizedGlobalConfig = { + // ... + admin: { + components: { // highlight-line + // ... + }, + }, +} +``` + +The following options are available: + +| Path | Description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| **`elements.SaveButton`** | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled. | +| **`elements.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. | +| **`elements.PublishButton`** | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. | +| **`elements.PreviewButton`** | Replace the default Preview Button with a Custom Component. [Preview](#preview) must be enabled. | +| **`views`** | Override or create new views within the Admin Panel. [More details](../admin/views). | + + + **Note:** + For details on how to build Custom Components, see [Building Custom Components](../admin/components#building-custom-components). + + +### Preview + +It is possible to display a Preview Button within the Edit View of the Admin Panel. This will allow editors to visit the frontend of your app the corresponds to the document they are actively editing. This way they can preview the latest, potentially unpublished changes. + +To configure the Preview Button, set the `admin.preview` property to a function in your Global Config: + +```ts +import { GlobalConfig } from 'payload' + +export const MainMenu: GlobalConfig = { + // ... + admin: { + // highlight-start + preview: (doc, { locale }) => { + if (doc?.slug) { + return `/${doc.slug}?locale=${locale}` + } + + return null + }, + // highlight-end + }, +} +``` + +The preview function receives two arguments: + +| Argument | Description | +| --- | --- | +| **`doc`** | The Document being edited. | +| **`ctx`** | An object containing `locale` and `token` properties. The `token` is the currently logged-in user's JWT. | + + + **Note:** + For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples). + ## GraphQL diff --git a/docs/configuration/overview.mdx b/docs/configuration/overview.mdx index d4801e458..64c421f21 100644 --- a/docs/configuration/overview.mdx +++ b/docs/configuration/overview.mdx @@ -108,7 +108,7 @@ _* An asterisk denotes that a property is required._ ### Typescript Config -Payload exposes a variety of TypeScript settings that you can leverage. These settings are used to auto-generate TypeScript interfaces for your [Collections](../configuration/collections) and [Globals](../configuration/globals), and to ensure that Payload uses your [Generated Types](../typescript/overview) for all [Local API](../local-api/overview) methods. +Payload exposes a variety of TypeScript settings that you can leverage. These settings are used to auto-generate TypeScript interfaces for your [Collections](./collections) and [Globals](./globals), and to ensure that Payload uses your [Generated Types](../typescript/overview) for all [Local API](../local-api/overview) methods. To customize the TypeScript settings, use the `typescript` property in your Payload Config: diff --git a/docs/fields/overview.mdx b/docs/fields/overview.mdx index e373f555d..88b9e3235 100644 --- a/docs/fields/overview.mdx +++ b/docs/fields/overview.mdx @@ -410,7 +410,7 @@ The following options are available: | **`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. | -## Field Descriptions +### Field Descriptions Field Descriptions are used to provide additional information to the editor about a field, such as special instructions. Their placement varies from field to field, but typically are displayed with subtle style differences beneath the field inputs. @@ -480,7 +480,7 @@ All Description Functions receive the following arguments: If you need to subscribe to live updates within your form, use a Description Component instead. [More details](#description). -## Conditional Logic +### Conditional Logic You can show and hide fields based on what other fields are doing by utilizing conditional logic on a field by field basis. The `condition` property on a field's admin config accepts a function which takes three arguments: @@ -519,7 +519,7 @@ The `condition` function should return a boolean that will control if the field } ``` -## Custom Components +### Custom Components Within the [Admin Panel](../admin/overview), fields are represented in three distinct places: @@ -561,7 +561,7 @@ The following options are available: | **`beforeInput`** | An array of elements that will be added before the input of the Field Component. [More details](#afterinput-and-beforeinput).| | **`afterInput`** | An array of elements that will be added after the input of the Field Component. [More details](#afterinput-and-beforeinput). | -### Field +#### Field 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. @@ -592,7 +592,7 @@ _For details on how to build Custom Components, see [Building Custom Components] Instead of replacing the entire Field Component, you can alternately replace or slot-in only specific parts by using the [`Label`](#label), [`Error`](#error), [`beforeInput`](#afterinput-and-beforinput), and [`afterInput`](#afterinput-and-beforinput) properties. -#### Default Props +##### Default Props All Field Components receive the following props by default: @@ -622,7 +622,7 @@ In addition to the above props, all Server Components will also receive the foll | **`user`** | The currently authenticated user. [More details](../authentication/overview). | | **`value`** | The value of the field at render-time. | -#### Sending and receiving values from the form +##### Sending and receiving values from the form When swapping out the `Field` component, you are responsible for sending and receiving the field's `value` from the form itself. @@ -648,7 +648,7 @@ export const CustomTextField: React.FC = () => { For a complete list of all available React hooks, see the [Payload React Hooks](../admin/hooks) documentation. For additional help, see [Building Custom Components](../admin/components#building-custom-components). -#### TypeScript +##### TypeScript#field-component-types When building Custom Field Components, you can import the client field props to ensure type safety in your component. There is an explicit type for the Field Component, one for every Field Type and server/client environment. The convention is to prepend the field type onto the target type, i.e. `TextFieldClientComponent`: @@ -664,7 +664,7 @@ import type { See each individual Field Type for exact type imports. -### Cell +#### 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. @@ -693,7 +693,7 @@ 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](../admin/components#building-custom-components). -### Filter +#### 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. @@ -717,7 +717,7 @@ All Custom Filter Components receive the same [Default Field Component Props](#f For details on how to build Custom Components themselves, see [Building Custom Components](../admin/components#building-custom-components). -### Label +#### 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. @@ -741,7 +741,7 @@ All Custom Label Components receive the same [Default Field Component Props](#fi For details on how to build Custom Components themselves, see [Building Custom Components](../admin/components#building-custom-components). -#### TypeScript +##### TypeScript#label-component-types When building Custom Label Components, you can import the component types to ensure type safety in your component. There is an explicit type for the Label Component, one for every Field Type and server/client environment. The convention is to append `LabelServerComponent` or `LabelClientComponent` to the type of field, i.e. `TextFieldLabelClientComponent`. @@ -753,7 +753,7 @@ import type { } from 'payload' ``` -### Description +#### Description Alternatively to the [Description Property](#field-descriptions), you can also use a [Custom Component](../admin/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. @@ -783,7 +783,7 @@ All Custom Description Components receive the same [Default Field Component Prop For details on how to build a Custom Components themselves, see [Building Custom Components](../admin/components#building-custom-components). -#### TypeScript +##### TypeScript#description-component-types When building Custom Description Components, you can import the component props to ensure type safety in your component. There is an explicit type for the Description Component, one for every Field Type and server/client environment. The convention is to append `DescriptionServerComponent` or `DescriptionClientComponent` to the type of field, i.e. `TextFieldDescriptionClientComponent`. @@ -795,7 +795,7 @@ import type { } from 'payload' ``` -### Error +#### Error The Error Component is rendered when a field fails validation. It is typically displayed beneath the field input in a visually-compelling style. @@ -819,7 +819,7 @@ All Error Components receive the [Default Field Component Props](#field). For details on how to build Custom Components themselves, see [Building Custom Components](../admin/components#building-custom-components). -#### TypeScript +##### TypeScript#error-component-types When building Custom Error Components, you can import the component types to ensure type safety in your component. There is an explicit type for the Error Component, one for every Field Type and server/client environment. The convention is to append `ErrorServerComponent` or `ErrorClientComponent` to the type of field, i.e. `TextFieldErrorClientComponent`. @@ -831,7 +831,7 @@ import type { } from 'payload' ``` -### afterInput and beforeInput +#### afterInput and beforeInput 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. diff --git a/docs/live-preview/overview.mdx b/docs/live-preview/overview.mdx index be49600f7..761c55036 100644 --- a/docs/live-preview/overview.mdx +++ b/docs/live-preview/overview.mdx @@ -30,12 +30,12 @@ const config = buildConfig({ ``` **Reminder:** - Alternatively, you can define the `admin.livePreview` property on individual [Collection Admin Configs](../admin/collections) and [Global Admin Configs](../admin/globals). Settings defined here will be merged into the top-level as overrides. + Alternatively, you can define the `admin.livePreview` property on individual [Collection Admin Configs](../configuration/collections#admin-options) and [Global Admin Configs](../configuration/globals#admin-options). Settings defined here will be merged into the top-level as overrides. ## Options -Setting up Live Preview is easy. This can be done either globally through the [Root Admin Config](../admin/overview), or on individual [Collection Admin Configs](../admin/collections) and [Global Admin Configs](../admin/globals). Once configured, a new "Live Preview" tab will appear at the top of enabled Documents. Navigating to this tab opens the preview window and loads your front-end application. +Setting up Live Preview is easy. This can be done either globally through the [Root Admin Config](../admin/overview), or on individual [Collection Admin Configs](../configuration/collections#admin-options) and [Global Admin Configs](../configuration/globals#admin-options). Once configured, a new "Live Preview" tab will appear at the top of enabled Documents. Navigating to this tab opens the preview window and loads your front-end application. The following options are available: @@ -104,8 +104,8 @@ The following arguments are provided to the `url` function: | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | **`data`** | The data of the Document being edited. This includes changes that have not yet been saved. | | **`locale`** | The locale currently being edited (if applicable). [More details](../configuration/localization). | -| **`collectionConfig`** | The Collection Admin Config of the Document being edited. [More details](../admin/collections). | -| **`globalConfig`** | The Global Admin Config of the Document being edited. [More details](../admin/globals). | +| **`collectionConfig`** | The Collection Admin Config of the Document being edited. [More details](../configuration/collections#admin-options). | +| **`globalConfig`** | The Global Admin Config of the Document being edited. [More details](../configuration/globals#admin-options). | | **`req`** | The Payload Request object. | If your application requires a fully qualified URL, such as within deploying to Vercel Preview Deployments, you can use the `req` property to build this URL: