diff --git a/docs/access-control/collections.mdx b/docs/access-control/collections.mdx index 275aeb66a..f19114a50 100644 --- a/docs/access-control/collections.mdx +++ b/docs/access-control/collections.mdx @@ -44,7 +44,7 @@ export const CollectionWithAccessControl: CollectionConfig = { unlock: () => {...}, // Version-enabled Collections only - readVersion: () => {...}, + readVersions: () => {...}, }, // highlight-end } diff --git a/docs/admin/collections.mdx b/docs/admin/collections.mdx new file mode 100644 index 000000000..ea11b9f53 --- /dev/null +++ b/docs/admin/collections.mdx @@ -0,0 +1,173 @@ +--- +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 { CollectionConfig } from 'payload' + +export const MyCollection: CollectionConfig = { + // ... + admin: { // highlight-line + // ... + }, +} +``` + +## Admin Options + +The following options are available: + +| Option | Description | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`group`** | Text used as a label for grouping Collection and Global links together in the navigation. | +| **`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](./overview). If no field is defined, the ID of the document is used as the title. | +| **`description`** | Text or React component to display below the Collection label in the List View to give editors more information. | +| **`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`** | Metadata overrides to apply to the [Admin Panel](./overview). Included properties are `description` and `openGraph`. | +| **`preview`** | Function to generate preview URLs within the [Admin Panel](./overview) 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](#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). | + +### 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' +import { CustomSaveButton } from './CustomSaveButton' + +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 | +| **`edit.SaveButton`** | Replace the default `Save` button with a Custom Component. Drafts must be disabled | +| **`edit.SaveDraftButton`** | Replace the default `Save Draft` button with a Custom Component. Drafts must be enabled and autosave must be disabled. | +| **`edit.PublishButton`** | Replace the default `Publish` button with a Custom Component. Drafts must be enabled. | +| **`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). | + + + 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 { 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 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). + + +### 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. + +To configure pagination options, use the `admin.pagination` property in your [Collection Config](../configuration/collections): + +```ts +import { 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 { 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 6aa795ae4..baccd9313 100644 --- a/docs/admin/components.mdx +++ b/docs/admin/components.mdx @@ -1,7 +1,7 @@ --- title: Swap in your own React components label: Custom Components -order: 20 +order: 40 desc: Fully customize your Admin Panel by swapping in your own React components. Add fields, remove views, update routes and change functions to sculpt your perfect Dashboard. keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- @@ -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](#collection-components) -- [Global Components](#global-components) +- [Collection Components](./collections#components) +- [Global Components](./globals#components) - [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. @@ -63,17 +63,18 @@ The following options are available: | **`logout.Button`** | The button displayed in the sidebar that logs the user out. | | **`graphics.Icon`** | The simplified logo used in contexts like the the `Nav` component. | | **`graphics.Logo`** | The full logo used in contexts like the `Login` view. | -| **`providers`** | Custom [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context) providers that will wrap the entire [Admin Panel](./overview). [More details](#custom-providers). | -| **`actions`** | An array of Custom Components to be rendered in the header of the [Admin Panel](./overview), providing additional interactivity and functionality. | -| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). | +| **`providers`** | Custom [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context) providers that will wrap the entire Admin Panel. [More details](#custom-providers). | +| **`actions`** | An array of Custom Components to be rendered in the header of the Admin Panel, providing additional interactivity and functionality. | +| **`views`** | Override or create new views within the Admin Panel. [More details](./views). | - Note: You can also use the `admin.components` property in your _[Collection](#collection-components) or [Global](#global-components)_. + Note: + You can also use set [Collection Components](./collections#components) and [Global Components](./globals#components) in their respective configs. ### 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 so you can export your own custom hooks, etc. To add a Custom Provider, use the `admin.components.providers` property in your [Payload Config](../getting-started/overview): @@ -115,80 +116,6 @@ export const useMyCustomContext = () => useContext(MyCustomContext) Reminder: 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. -## 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. - -To override Collection Components, use the `admin.components` property in your [Collection Config](../configuration/collections): - -```ts -import type { SanitizedCollectionConfig } from 'payload' -import { CustomSaveButton } from './CustomSaveButton' - -export const MyCollection: SanitizedCollectionConfig = { - slug: 'my-collection', - admin: { - components: { - edit: { - SaveButton: CustomSaveButton, // highlight-line - }, - }, - }, - // ... -} -``` - -_For details on how to build Custom Components, see [Building Custom Components](#building-custom-components)._ - -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 | -| **`edit.SaveButton`** | Replace the default `Save` button with a Custom Component. Drafts must be disabled | -| **`edit.SaveDraftButton`** | Replace the default `Save Draft` button with a Custom Component. Drafts must be enabled and autosave must be disabled. | -| **`edit.PublishButton`** | Replace the default `Publish` button with a Custom Component. Drafts must be enabled. | -| **`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). | - -## 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. - -To override Global Components, use the `admin.components` property in your [Global Config](../configuration/globals): - -```ts -import type { SanitizedGlobalConfig } from 'payload' -import { CustomSaveButton } from './CustomSaveButton' - -export const MyGlobal: SanitizedGlobalConfig = { - slug: 'my-global', - admin: { - components: { - elements: { - SaveButton: CustomSaveButton, // highlight-line - }, - }, - }, - // ... -} -``` - -_For details on how to build Custom Components, see [Building Custom Components](#building-custom-components)._ - -The following options are available: - -| Path | Description | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| **`elements.SaveButton`** | Replace the default `Save` button with a Custom Component. Drafts must be disabled. | -| **`elements.SaveDraftButton`** | Replace the default `Save Draft` button with a Custom Component. Drafts must be enabled and autosave must be disabled. | -| **`elements.PublishButton`** | Replace the default `Publish` button with a Custom Component. Drafts must be enabled. | -| **`elements.PreviewButton`** | Replace the default `Preview` button with a Custom Component. | -| **`views`** | Override or create new views within the [Admin Panel](./overview). [More details](./views). | - ## 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) directly on the front-end, among other things. diff --git a/docs/admin/customizing-css.mdx b/docs/admin/customizing-css.mdx index a0194c525..593f845a2 100644 --- a/docs/admin/customizing-css.mdx +++ b/docs/admin/customizing-css.mdx @@ -1,7 +1,7 @@ --- title: Customizing CSS & SCSS label: Customizing CSS -order: 60 +order: 80 desc: Customize the Payload Admin Panel further by adding your own CSS or SCSS style sheet to the configuration, powerful theme and design options are waiting for you. keywords: admin, css, scss, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- diff --git a/docs/admin/fields.mdx b/docs/admin/fields.mdx index 828ea6d49..0f1c35b46 100644 --- a/docs/admin/fields.mdx +++ b/docs/admin/fields.mdx @@ -1,7 +1,7 @@ --- title: Customizing Fields label: Customizing Fields -order: 40 +order: 60 desc: keywords: --- diff --git a/docs/admin/globals.mdx b/docs/admin/globals.mdx new file mode 100644 index 000000000..1cc04b901 --- /dev/null +++ b/docs/admin/globals.mdx @@ -0,0 +1,108 @@ +--- +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 used as a label for grouping Collection and Global links together in the navigation. | +| **`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](#components). | +| **`preview`** | Function to generate a preview URL within the [Admin Panel](./overview) 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`** | Metadata overrides to apply to the [Admin Panel](./overview). Included properties are `description` and `openGraph`. | + +### 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' +import { CustomSaveButton } from './CustomSaveButton' + +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 must be disabled. | +| **`elements.SaveDraftButton`** | Replace the default `Save Draft` button with a Custom Component. Drafts must be enabled and autosave must be disabled. | +| **`elements.PublishButton`** | Replace the default `Publish` button with a Custom Component. Drafts must be enabled. | +| **`elements.PreviewButton`** | Replace the default `Preview` button with a Custom Component. | +| **`views`** | Override or create new views within the [Admin Panel](./overview). [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/hooks.mdx b/docs/admin/hooks.mdx index 44ef9f120..d06ed7e5b 100644 --- a/docs/admin/hooks.mdx +++ b/docs/admin/hooks.mdx @@ -1,7 +1,7 @@ --- title: React Hooks label: React Hooks -order: 50 +order: 70 desc: Make use of all of the powerful React hooks that Payload provides. keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- diff --git a/docs/admin/overview.mdx b/docs/admin/overview.mdx index 421018721..3e75c2b6b 100644 --- a/docs/admin/overview.mdx +++ b/docs/admin/overview.mdx @@ -102,7 +102,7 @@ The following options are available: Reminder: - These are the _root-level_ options for the Admin Panel. You can also customize the admin options for _Collections and Globals_ through their respective `admin` keys. + 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. ### The Admin User Collection diff --git a/docs/admin/preferences.mdx b/docs/admin/preferences.mdx index b85be67a7..c5b0d5a5a 100644 --- a/docs/admin/preferences.mdx +++ b/docs/admin/preferences.mdx @@ -1,7 +1,7 @@ --- title: Managing User Preferences label: Preferences -order: 50 +order: 70 desc: Store the preferences of your users as they interact with the Admin Panel. keywords: admin, preferences, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- diff --git a/docs/admin/views.mdx b/docs/admin/views.mdx index 349629aa5..665e39e3c 100644 --- a/docs/admin/views.mdx +++ b/docs/admin/views.mdx @@ -1,7 +1,7 @@ --- title: Customizing Views label: Customizing Views -order: 30 +order: 50 desc: keywords: --- diff --git a/docs/configuration/collections.mdx b/docs/configuration/collections.mdx index c4312aff7..b314ba5b7 100644 --- a/docs/configuration/collections.mdx +++ b/docs/configuration/collections.mdx @@ -59,15 +59,15 @@ The following options are available: | Option | Description | |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **`admin`** | The configuration options for the Admin Panel. [More details](#admin-options). | +| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/collections). | | **`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. For more, consult the [Authentication](../authentication/config) documentation. | +| **`auth`** | Specify options if you would like this Collection to feature authentication. [More details](../authentication/config). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`disableDuplicate`** | When true, do not show the "Duplicate" button while editing documents within this Collection and prevent `duplicate` from all APIs. | | **`defaultSort`** | Pass a top-level field to sort by default in the Collection List View. Prefix the name of the field with a minus symbol ("-") to sort in descending order. | | **`dbName`** | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. | | **`endpoints`** | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints). | -| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [Click here](../fields/overview) for a full list of field types as well as how to configure them. | +| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [More details](../fields/overview). | | **`graphQL`** | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL. | | **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#collection-hooks). | | **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. | @@ -93,130 +93,7 @@ Fields define the schema of the Documents within a Collection. To learn more, go ### Admin Options -You can customize the way that the [Admin Panel](../admin/overview) behaves on a Collection-by-Collection basis. - -To configure Admin Options for Collections, use the `admin` property in your Collection Config: - -```ts -import { CollectionConfig } from 'payload' - -export const Posts: CollectionConfig = { - // ... - admin: { // highlight-line - // ... - }, -} -``` - -The following options are available: - -| Option | Description | -| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`group`** | Text used as a label for grouping Collection and Global links together in the navigation. | -| **`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](#admin-hooks). | -| **`useAsTitle`** | Specify a top-level field to use for a document title throughout the [Admin Panel](../admin/overview). If no field is defined, the ID of the document is used as the title. | -| **`description`** | Text or React component to display below the Collection label in the List View to give editors more information. | -| **`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`** | Metadata overrides to apply to the [Admin Panel](../admin/overview). Included properties are `description` and `openGraph`. | -| **`preview`** | Function to generate preview URLs within the [Admin Panel](../admin/overview) 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](../admin/components#collections). | -| **`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). | - -#### Preview - -It is possible to display a Preview Button in the Admin Panel within the Edit View. 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 { 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 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. | - - - Reminder: - 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. - -To configure pagination options, use the `admin.pagination` property in your Collection Config: - -```ts -import { 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 { 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. - +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. ## TypeScript diff --git a/docs/configuration/globals.mdx b/docs/configuration/globals.mdx index bb9418feb..3359849d7 100644 --- a/docs/configuration/globals.mdx +++ b/docs/configuration/globals.mdx @@ -68,12 +68,12 @@ 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-options). | +| **`admin`** | The configuration options for the Admin Panel. [More details](../admin/globals). | | **`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. | | **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). | -| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [Click here](../fields/overview) for a full list of field types as well as how to configure them. | +| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). | | **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. | | **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#global-hooks). | | **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. | @@ -97,69 +97,7 @@ Fields define the schema of the Global. To learn more, go to the [Fields](../fie ### Admin Options -You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis. - -To configure Admin Options for Globals, use the `admin` property in your Global Config: - -```ts -import { GlobalConfig } from 'payload' - -const MyGlobal: GlobalConfig = { - // ... - admin: { // highlight-line - // ... - }, -} -``` - -The following options are available: - -| Option | Description | -| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **`group`** | Text used as a label for grouping Collection and Global links together in the navigation. | -| **`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](../admin/components#globals). | -| **`preview`** | Function to generate a preview URL within the [Admin Panel](../admin/overview) 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`** | Metadata overrides to apply to the [Admin Panel](../admin/overview). Included properties are `description` and `openGraph`. | - -#### Preview - -It is possible to display a Preview Button in the Admin Panel within the Edit View. 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. | - - - Reminder: - 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). - +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. ## TypeScript