316 lines
14 KiB
Plaintext
316 lines
14 KiB
Plaintext
---
|
|
title: Customizing Views
|
|
label: Customizing Views
|
|
order: 30
|
|
desc:
|
|
keywords:
|
|
---
|
|
|
|
### Root
|
|
|
|
You can easily swap entire views with your own by using the `admin.components.views` property. At the root level, Payload renders the following views by default, all of which can be overridden:
|
|
|
|
| Property | Description |
|
|
| --------------- | ----------------------------------------------------------------------------- |
|
|
| **`Account`** | The Account view is used to show the currently logged in user's Account page. |
|
|
| **`Dashboard`** | The main landing page of the [Admin Panel](./overview). |
|
|
|
|
To swap out any of these views, simply pass in your custom component to the `admin.components.views` property of your Payload config. For example:
|
|
|
|
```ts
|
|
// payload.config.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Account: MyCustomAccountView,
|
|
Dashboard: MyCustomDashboardView,
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For more granular control, pass a configuration object instead. Payload exposes the following properties for each view:
|
|
|
|
| Property | Description |
|
|
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| **`Component`** \* | Pass in the component that should be rendered when a user navigates to this route. |
|
|
| **`path`** \* | Any valid URL path or array of paths that [`path-to-regexp`](https://www.npmjs.com/package/path-to-regex) understands. |
|
|
| **`exact`** | Boolean. When true, will only match if the path matches the `usePathname()` exactly. |
|
|
| **`strict`** | When true, a path that has a trailing slash will only match a location.pathname with a trailing slash. This has no effect when there are additional URL segments in the location.pathname. |
|
|
| **`sensitive`** | When true, will match if the path is case sensitive. |
|
|
|
|
_\* An asterisk denotes that a property is required._
|
|
|
|
#### Adding new root views
|
|
|
|
To add a _new_ view to the [Admin Panel](./overview), simply add another key to the `views` object with at least a `path` and `Component` property. For example:
|
|
|
|
```ts
|
|
// payload.config.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
MyCustomView: {
|
|
Component: MyCustomView,
|
|
path: '/my-custom-view',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="warning">
|
|
<strong>Note:</strong>
|
|
<br />
|
|
Routes are cascading. This means that unless explicitly given the `exact` property, they will
|
|
match on URLs that simply _start_ with the route's path. This is helpful when creating catch-all
|
|
routes in your application. Alternatively, you could define your nested route _before_ your parent
|
|
route.
|
|
</Banner>
|
|
|
|
For help on how to build your own custom view components, see [Building Custom View Components](#building-custom-view-components). For more examples regarding how to customize components, [look at the following examples](https://github.com/payloadcms/payload/tree/main/test/admin/components)._
|
|
|
|
### Collections
|
|
|
|
To swap out entire views on collections, you can use the `admin.components.views` property on the collection's config. Payload renders the following views by default, all of which can be overridden:
|
|
|
|
| Property | Description |
|
|
| ---------- | ------------------------------------------------------------------------- |
|
|
| **`Edit`** | The Edit view is used to edit a single document for a given collection. |
|
|
| **`List`** | The List view is used to show a list of documents for a given collection. |
|
|
|
|
To swap out any of these views, simply pass in your custom component to the `admin.components.views` property of your Payload config. This will replace the entire view, including the page breadcrumbs, title, tabs, etc, _as well as all nested routes_.
|
|
|
|
```ts
|
|
// Collection.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: MyCustomEditView,
|
|
List: MyCustomListView,
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For help on how to build your own custom view components, see [Building Custom View Components](#building-custom-view-components).
|
|
|
|
**Customizing Nested Views within 'Edit' in Collections**
|
|
|
|
The `Edit` view in collections consists of several nested views, each serving a unique purpose. You can customize these nested views using the `admin.components.views.Edit` property in the collection's configuration. This approach allows you to replace specific nested views while keeping the overall structure of the `Edit` view intact, including the page breadcrumbs, title, tabs, etc.
|
|
|
|
Here's an example of how you can customize nested views within the `Edit` view in collections, including the use of the `actions` property:
|
|
|
|
```ts
|
|
// Collection.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: {
|
|
Default: {
|
|
Component: MyCustomDefaultTab,
|
|
actions: [CollectionEditButton], // Custom actions for the default edit view
|
|
},
|
|
API: {
|
|
Component: MyCustomAPIView,
|
|
actions: [CollectionAPIButton], // Custom actions for API view
|
|
},
|
|
LivePreview: {
|
|
Component: MyCustomLivePreviewView,
|
|
actions: [CollectionLivePreviewButton], // Custom actions for Live Preview
|
|
},
|
|
Version: {
|
|
Component: MyCustomVersionView,
|
|
actions: [CollectionVersionButton], // Custom actions for Version view
|
|
},
|
|
Versions: {
|
|
Component: MyCustomVersionsView,
|
|
actions: [CollectionVersionsButton], // Custom actions for Versions view
|
|
},
|
|
},
|
|
List: {
|
|
actions: [CollectionListButton],
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
**Adding New Tabs to 'Edit' View**
|
|
|
|
You can also add _new_ tabs to the `Edit` view by adding another key to the `components.views.Edit[key]` object with a `path` and `Component` property. See [Custom Tabs](#custom-tabs) for more information.
|
|
|
|
### Globals
|
|
|
|
To swap out views for globals, you can use the `admin.components.views` property on the global's config. Payload renders the following views by default, all of which can be overridden:
|
|
|
|
| Property | Description |
|
|
| ---------- | ------------------------------------------------------------------- |
|
|
| **`Edit`** | The Edit view is used to edit a single document for a given Global. |
|
|
|
|
To swap out any of these views, simply pass in your custom component to the `admin.components.views` property of your Payload config. This will replace the entire view, including the page breadcrumbs, title, and tabs, _as well as all nested views_.
|
|
|
|
```ts
|
|
// Global.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: MyCustomEditView,
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For help on how to build your own custom view components, see [Building Custom View Components](#building-custom-view-components).
|
|
|
|
**Customizing Nested Views within 'Edit' in Globals**
|
|
|
|
Similar to collections, Globals allow for detailed customization within the `Edit` view. This includes the ability to swap specific nested views while maintaining the overall structure of the `Edit` view. You can use the `admin.components.views.Edit` property in the Globals configuration to achieve this, and this will only replace the nested view, leaving the page breadcrumbs, title, and tabs intact.
|
|
|
|
Here's how you can customize nested views within the `Edit` view in Globals, including the use of the `actions` property:
|
|
|
|
```ts
|
|
// Global.ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: {
|
|
Default: {
|
|
Component: MyCustomGlobalDefaultTab,
|
|
actions: [GlobalEditButton], // Custom actions for the default edit view
|
|
},
|
|
API: {
|
|
Component: MyCustomGlobalAPIView,
|
|
actions: [GlobalAPIButton], // Custom actions for API view
|
|
},
|
|
LivePreview: {
|
|
Component: MyCustomGlobalLivePreviewView,
|
|
actions: [GlobalLivePreviewButton], // Custom actions for Live Preview
|
|
},
|
|
Version: {
|
|
Component: MyCustomGlobalVersionView,
|
|
actions: [GlobalVersionButton], // Custom actions for Version view
|
|
},
|
|
Versions: {
|
|
Component: MyCustomGlobalVersionsView,
|
|
actions: [GlobalVersionsButton], // Custom actions for Versions view
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
You can also add _new_ tabs to the `Edit` view by adding another key to the `components.views.Edit[key]` object with a `path` and `Component` property. See [Custom Tabs](#custom-tabs) for more information.
|
|
|
|
### Custom Tabs
|
|
|
|
You can easily swap individual collection or global edit views. To do this, pass an _object_ to the `admin.components.views.Edit` property of the config. Payload renders the following views by default, all of which can be overridden:
|
|
|
|
| Property | Description |
|
|
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`Default`** | The Default view is the primary view in which your document is edited. |
|
|
| **`Versions`** | The Versions view is used to view the version history of a single document. [More details](../versions) |
|
|
| **`Version`** | The Version view is used to view a single version of a single document for a given collection. [More details](../versions). |
|
|
| **`API`** | The API view is used to display the REST API JSON response for a given document. |
|
|
| **`LivePreview`** | The LivePreview view is used to display the Live Preview interface. [More details](../live-preview) |
|
|
|
|
Here is an example:
|
|
|
|
```ts
|
|
// Collection.ts or Global.ts
|
|
export const MyCollection: SanitizedCollectionConfig = {
|
|
slug: 'my-collection',
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: {
|
|
// You can also define `components.views.Edit` as a component, this will override _all_ nested views
|
|
Default: MyCustomDefaultTab,
|
|
Versions: MyCustomVersionsTab,
|
|
Version: MyCustomVersionTab,
|
|
API: MyCustomAPITab,
|
|
LivePreview: MyCustomLivePreviewTab,
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
To add a _new_ tab to the `Edit` view, simply add another key to `components.views.Edit[key]` with at least a `path` and `Component` property. For example:
|
|
|
|
```ts
|
|
// `Collection.ts` or `Global.ts`
|
|
export const MyCollection: SanitizedCollectionConfig = {
|
|
slug: 'my-collection',
|
|
admin: {
|
|
components: {
|
|
views: {
|
|
Edit: {
|
|
MyCustomTab: {
|
|
Component: MyCustomTab,
|
|
path: '/my-custom-tab',
|
|
// You an swap the entire tab component out for your own
|
|
Tab: MyCustomTab,
|
|
},
|
|
AnotherCustomView: {
|
|
Component: AnotherCustomView,
|
|
path: '/another-custom-view',
|
|
// Or you can use the default tab component and just pass in your own label and href
|
|
Tab: {
|
|
label: 'Another Custom View',
|
|
href: '/another-custom-view',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
### Building Custom View Components
|
|
|
|
Your custom view components will be provided with the following props:
|
|
|
|
| Prop | Description |
|
|
| ----------------------- | ---------------------------------------------------------------------------- |
|
|
| **`user`** | The currently logged in user. Will be `null` if no user is logged in. |
|
|
| **`canAccessAdmin`** \* | If the currently logged in user is allowed to access the [Admin Panel](./overview) or not. |
|
|
|
|
<Banner type="warning">
|
|
<strong>Note:</strong>
|
|
<br />
|
|
It's up to you to secure your custom views. If your view requires a user to be logged in or to
|
|
have certain access rights, you should handle that within your view component yourself.
|
|
</Banner>
|
|
|
|
### Examples
|
|
|
|
You can find examples of custom views in the [Payload source code `/test/admin/components/views` folder](https://github.com/payloadcms/payload/tree/main/test/admin/components/views). There, you'll find two custom views:
|
|
|
|
1. A custom view that uses the `DefaultTemplate`, which is the built-in Payload template that displays the sidebar and "eyebrow nav"
|
|
1. A custom view that uses the `MinimalTemplate` - which is just a centered template used for things like logging in or out
|
|
|
|
To see how to pass in your custom views to create custom views of your own, take a look at the `admin.components.views` property of the [Payload test admin config](https://github.com/payloadcms/payload/blob/main/test/admin/config.ts).
|
|
|