1fc9c47f20
Similar to #9746. When deploying to Vercel, preview deployment URLs are dynamically generated. This breaks `admin.preview` within those deployments because there is no mechanism by which we can detect and set that URL within Payload. Although Vercel provides various environment variables at our disposal, they provide no concrete identifier for exactly which URL is being currently previewed (you can access the same deployment from a number of different URLs). The fix is to support relative `admin.preview` URLs, that way Payload can prepend the application's top-level domain dynamically at render-time in order to create a fully qualified URL. So when you visit a Vercel preview deployment, for example, that deployment's unique URL is used as the preview redirect, instead of the application's root/production domain. Note: this does not fix multi-tenancy single-domain setups, as those still require a static top-level domain for each tenant.
177 lines
12 KiB
Plaintext
177 lines
12 KiB
Plaintext
---
|
|
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 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. 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. |
|
|
| **`views`** | Override or create new views within the Admin Panel. [More details](./views). |
|
|
|
|
<Banner type="success">
|
|
<strong>Note:</strong>
|
|
For details on how to build Custom Components, see [Building Custom Components](./components#building-custom-components).
|
|
</Banner>
|
|
|
|
### 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. If you are using a relative path, Payload will prepend the application's origin onto it, creating a fully qualified URL.
|
|
|
|
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. |
|
|
|
|
<Banner type="success">
|
|
<strong>Note:</strong>
|
|
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).
|
|
</Banner>
|
|
|
|
### 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
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="warning">
|
|
<strong>Tip:</strong>
|
|
If you are adding `listSearchableFields`, make sure you index each of these fields so your admin queries can remain performant.
|
|
</Banner>
|