tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: custom views (#3483)

Browse Source
This commit is contained in:
Jacob Fletcher
2023-10-08 19:34:23 -04:00
committed by GitHub
parent 5a969a2c4d
commit 8255088f39
6 changed files with 223 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

307
docs/admin/components.mdx
View File

@@ -6,15 +6,15 @@ desc: Fully customize your Admin Panel by swapping in your own React components.
keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, express keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, express
--- ---
While designing the Payload Admin panel, we determined it should be as minimal and straightforward as possible to allow easy customization and control. There are many times where you may want to completely control how a whole view or a field works. You might even want to add in your own routes entirely. In order for Payload to support that level of customization without introducing versioning / future-proofing issues, Payload provides for a pattern to supply your own React components via your Payload config. While designing the Payload Admin panel, we determined it should be as minimal and straightforward as possible to allow easy customization and control. There are many times where you may want to completely control how a whole view or a field works. You might even want to add in new views entirely. In order for Payload to support this level of customization without introducing versioning / future-proofing issues, Payload provides for a pattern to supply your own React components via your Payload config.
To swap in your own React component, first, consult the list of available component overrides below. Determine the scope that corresponds to what you are trying to accomplish, and then author your React component accordingly. To swap in your own React component, first, consult the list of available component overrides below. Determine the scope that corresponds to what you are trying to accomplish, and then author your React component accordingly.
<Banner type="success"> <Banner type="success">
<strong>Tip:</strong> <strong>Tip:</strong>
<br /> <br />
Custom components will automatically be provided with all props that the default component would Custom components will automatically be provided with all props that the default component normally
accept. accepts.
</Banner> </Banner>
### Base Component Overrides ### Base Component Overrides
@@ -23,27 +23,26 @@ You can override a set of admin panel-wide components by providing a component t
| Path | Description | | Path | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Nav`** | Contains the sidebar and mobile Nav in its entirety. | | **`Nav`** | Contains the sidebar / mobile menu in its entirety. |
| **`logout.Button`** | A custom React component. | | **`BeforeNavLinks`** | Array of components to inject into the built-in Nav, _before_ the links themselves. |
| **`AfterNavLinks`** | Array of components to inject into the built-in Nav, _after_ the links. |
| **`BeforeDashboard`** | Array of components to inject into the built-in Dashboard, _before_ the default dashboard contents. | | **`BeforeDashboard`** | Array of components to inject into the built-in Dashboard, _before_ the default dashboard contents. |
| **`AfterDashboard`** | Array of components to inject into the built-in Dashboard, _after_ the default dashboard contents. [Demo](https://github.com/payloadcms/payload/tree/master/test/admin/components/AfterDashboard/index.tsx) | | **`AfterDashboard`** | Array of components to inject into the built-in Dashboard, _after_ the default dashboard contents. [Demo](https://github.com/payloadcms/payload/tree/master/test/admin/components/AfterDashboard/index.tsx) |
| **`BeforeLogin`** | Array of components to inject into the built-in Login, _before_ the default login form. | | **`BeforeLogin`** | Array of components to inject into the built-in Login, _before_ the default login form. |
| **`AfterLogin`** | Array of components to inject into the built-in Login, _after_ the default login form. | | **`AfterLogin`** | Array of components to inject into the built-in Login, _after_ the default login form. |
| **`BeforeNavLinks`** | Array of components to inject into the built-in Nav, _before_ the links themselves. | | **`logout.Button`** | A custom React component. |
| **`AfterNavLinks`** | Array of components to inject into the built-in Nav, _after_ the links. |
| **`views.Account`** | The Account view is used to show the currently logged in user's Account page. |
| **`views.Dashboard`** | The main landing page of the Admin panel. |
| **`graphics.Icon`** | Used as a graphic within the `Nav` component. Often represents a condensed version of a full logo. | | **`graphics.Icon`** | Used as a graphic within the `Nav` component. Often represents a condensed version of a full logo. |
| **`graphics.Logo`** | The full logo to be used in contexts like the `Login` view. | | **`graphics.Logo`** | The full logo to be used in contexts like the `Login` view. |
| **`routes`** | Define your own routes to add to the Payload Admin UI. [More](#custom-routes) |
| **`providers`** | Define your own provider components that will wrap the Payload Admin UI. [More](#custom-providers) | | **`providers`** | Define your own provider components that will wrap the Payload Admin UI. [More](#custom-providers) |
| **`views`** | Override or create new views within the Payload Admin UI. [More](#views) |
#### Full example: Here is a full example showing how to swap some of these components for your own.
`payload.config.js` `payload.config.js`
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'
import { import {
MyCustomNav, MyCustomNav,
MyCustomLogo, MyCustomLogo,
@@ -71,31 +70,88 @@ export default buildConfig({
}) })
``` ```
_For more examples regarding how to customize components, look at the following [examples](https://github.com/payloadcms/payload/tree/master/test/admin/components)._ #### Views
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 that 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. |
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 all of the properties of `<Route />` component in [React Router v5](https://v5.reactrouter.com):
| Property | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **`Component`** \* | Pass in the component that should be rendered when a user navigates to this route. |
| **`path`** \* | React Router `path`. [See the React Router docs](https://v5.reactrouter.com/web/api/Route/path-string-string) for more info. |
| **`exact`** | React Router `exact` property. [More](https://v5.reactrouter.com/web/api/Route/exact-bool) |
| **`strict`** | React Router `strict` property. [More](https://v5.reactrouter.com/web/api/Route/strict-bool) |
| **`sensitive`** | React Router `sensitive` property. [More](https://v5.reactrouter.com/web/api/Route/sensitive-bool) |
_\* An asterisk denotes that a property is required._
#### Adding new views
To add a _new_ view to the Admin Panel, 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',
},
},
},
},
}
```
_For more examples regarding how to customize components, look at the following [examples](https://github.com/payloadcms/payload/tree/master/test/admin/components)._ For help on how to build your own custom view components, see the [Building a custom view component](#building-a-custom-view-component) section.
### Collections ### Collections
You can override components on a Collection-by-Collection basis via each Collection's `admin` property. You can override components on a collection-by-collection basis via their `admin` property.
| Path | Description | | Path | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`views.Edit`** | Used while a document within this Collection is being edited. | | **`BeforeList`** | Array of components to inject _before_ the built-in List view |
| **`views.List`** | The `List` view is used to render a paginated, filterable table of Documents in this Collection. | | **`BeforeListTable`** | Array of components to inject _before_ the built-in List view's table |
| **`AfterList`** | Array of components to inject _after_ the built-in List view |
| **`AfterListTable`** | 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.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.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.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. | | **`edit.PreviewButton`** | Replace the default `Preview` button with a custom component. |
| **`BeforeList`** | Array of components to inject _before_ the built-in List view | | **`views`** | Override or create new views within the Payload Admin UI. [More](#collection-views) |
| **`BeforeListTable`** | Array of components to inject _before_ the built-in List view's table |
| **`AfterListTable`** | Array of components to inject _after_ the built-in List view's table |
| **`AfterList`** | Array of components to inject _after_ the built-in List view |
#### Examples Here is a full example showing how to swap some of these components for your own:
`Collection.ts`
```tsx ```tsx
// Custom Buttons
import * as React from 'react' import * as React from 'react'
import { import {
CustomSaveButtonProps, CustomSaveButtonProps,
CustomSaveDraftButtonProps, CustomSaveDraftButtonProps,
@@ -133,56 +189,166 @@ export const CustomPreviewButton: CustomPreviewButtonProps = ({
}) => { }) => {
return <DefaultButton label={label} disabled={disabled} preview={preview} /> return <DefaultButton label={label} disabled={disabled} preview={preview} />
} }
export const MyCollection: SanitizedCollectionConfig = {
slug: 'my-collection',
admin: {
components: {
edit: {
SaveButton: CustomSaveButton,
SaveDraftButton: CustomSaveDraftButton,
PublishButton: CustomPublishButton,
PreviewButton: CustomPreviewButton,
},
},
}
}
``` ```
##### Custom Collection List View Example #### Collection views
Collection.ts 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 that can be overridden:
```tsx | Property | Description |
import { MyListComponent } from './MyListComponent'; | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
export const MyCollection: CollectionConfig = { | **`Edit`** | The Edit view is used to edit a single document for a given Collection. |
slug: 'mycollection', | **`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. For example:
```ts
// Collection.ts
export const MyCollection: SanitizedCollectionConfig = {
slug: 'my-collection',
admin: { admin: {
components: { components: {
views: { views: {
List: MyListComponent, Edit: MyCustomEditView,
List: MyCustomListView,
}, },
}, },
}, },
fields: [ }
...
],
};
``` ```
MyListComponent.tsx To swap or add new _tabs_ to the `Edit` view, you can use the `admin.components.views.Edit` property on the collection's config. See the [Custom Tabs](#custom-tabs) section for more information. For help on how to build your own custom view components, see the [Building a custom view component](#building-a-custom-view-component) section.
```tsx
import React from 'react'
import { List, type Props } from 'payload/components/views/List' // Payload's default List view component and its props
export const MyListComponent: React.FC<Props> = (props) => (
<div>
<p>
Some text before the default list view component. If you just want to do that, you can also
use the admin.components.list.BeforeList hook
</p>
<List {...props} />
</div>
)
```
### Globals ### Globals
As with Collections, You can override components on a global-by-global basis via their `admin` property. As with Collections, you can override components on a global-by-global basis via their `admin` property.
| Path | Description | | Path | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`views.Edit`** | Used while this Global is being edited. |
| **`edit.SaveButton`** | Replace the default `Save` button with a custom component. Drafts must be disabled | | **`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.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.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. | | **`edit.PreviewButton`** | Replace the default `Preview` button with a custom component. |
| **`views`** | Override or create new views within the Payload Admin UI. [More](#global-views) |
#### Global views
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 that you can override:
| 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. For example:
```ts
export const MyGlobal: SanitizedGlobalConfig = {
slug: 'my-global',
admin: {
components: {
views: {
Edit: MyCustomEditView,
},
},
},
}
```
To swap or add new _tabs_ to the `Edit` view, you can use the `admin.components.views.Edit` property on the collection's config. See the [Custom Tabs](#custom-tabs) section for more information. For help on how to build your own custom view components, see the [Building a custom view component](#building-a-custom-view-component) section.
### Custom Tabs
To can swap collection or global tabs, pass an _object_ to the `admin.components.views.Edit` property on any collection or global config. Payload renders the following views by default 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: {
Default: MyCustomDefaultTab,
Versions: MyCustomVersionsTab,
Version: MyCustomVersionTab,
API: MyCustomAPITab,
LivePreview: MyCustomLivePreviewTab,
},
},
},
},
}
```
To add a _new_ tab to the `Edit` view, simply add another key to the `views.Edit` object 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',
},
},
},
},
},
}
```
### Building a custom view component
Your custom view components will be given all the props that a React Router `<Route />` typically would receive, as well as two props from Payload:
| 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 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>
#### Example
You can find examples of custom views in the [Payload source code `/test/admin/components/views` folder](https://github.com/payloadcms/payload/tree/master/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/master/test/admin/config.ts).
### Fields ### Fields
@@ -257,47 +423,6 @@ const CustomTextField: React.FC<Props> = ({ path }) => {
components, including the <strong>useField</strong> hook, [click here](/docs/admin/hooks). components, including the <strong>useField</strong> hook, [click here](/docs/admin/hooks).
</Banner> </Banner>
## Custom routes
You can easily add your own custom routes to the Payload Admin panel using the `admin.components.routes` property. Payload currently uses the extremely powerful React Router v5.x and custom routes support all the properties of the React Router `<Route />` component.
**Custom routes support the following properties:**
| Property | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **`Component`** \* | Pass in the component that should be rendered when a user navigates to this route. |
| **`path`** \* | React Router `path`. [See the React Router docs](https://v5.reactrouter.com/web/api/Route/path-string-string) for more info. |
| **`exact`** | React Router `exact` property. [More](https://v5.reactrouter.com/web/api/Route/exact-bool) |
| **`strict`** | React Router `strict` property. [More](https://v5.reactrouter.com/web/api/Route/strict-bool) |
| **`sensitive`** | React Router `sensitive` property. [More](https://v5.reactrouter.com/web/api/Route/sensitive-bool) |
_\* An asterisk denotes that a property is required._
#### Custom route components
Your custom route components will be given all the props that a React Router `<Route />` typically would receive, as well as two props from Payload:
| 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 or not. |
<Banner type="warning">
<strong>Note:</strong>
<br />
It's up to you to secure your custom routes. If your route requires a user to be logged in or to
have certain access rights, you should handle that within your route component yourself.
</Banner>
#### Example
You can find examples of custom route views in the [Payload source code `/test/admin/components/views` folder](https://github.com/payloadcms/payload/tree/master/test/admin/components/views). There, you'll find two custom routes:
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 routes of your own, take a look at the `admin.components.routes` property of the [Payload test admin config](https://github.com/payloadcms/payload/blob/master/test/admin/config.ts).
## Custom providers ## Custom providers
As your admin customizations gets more complex you may want to share state between fields or other components. You can add custom providers to do add your own context to any Payload app for use in other custom components within the admin panel. Within your config add `admin.components.providers`, these can be used to share context or provide other custom functionality. Read the [React context](https://reactjs.org/docs/context.html) docs to learn more. As your admin customizations gets more complex you may want to share state between fields or other components. You can add custom providers to do add your own context to any Payload app for use in other custom components within the admin panel. Within your config add `admin.components.providers`, these can be used to share context or provide other custom functionality. Read the [React context](https://reactjs.org/docs/context.html) docs to learn more.

3
docs/cloud/projects.mdx
View File

@@ -43,12 +43,13 @@ From the Environment Variables page of the Settings tab, you can add, update and
with `PAYLOAD_PUBLIC_`.  Learn more with `PAYLOAD_PUBLIC_`.  Learn more
[here](https://payloadcms.com/docs/admin/webpack#admin-environment-vars). [here](https://payloadcms.com/docs/admin/webpack#admin-environment-vars).
</Banner> </Banner>
### Custom Domains ### Custom Domains
With Payload Cloud, you can add custom domain names to your project. To do so, first go to the Domains page of the Settings tab of your project. Here you can see your default domain. To add a new domain, type in the domain name you wish to use. With Payload Cloud, you can add custom domain names to your project. To do so, first go to the Domains page of the Settings tab of your project. Here you can see your default domain. To add a new domain, type in the domain name you wish to use.
<Banner> <Banner>
Note: do not include the protocol (http:// or https://) or any routes (/page). Only include the Note: do not include the protocol (http:// or https://) or any paths (/page). Only include the
domain name and extension, and optionally a subdomain. - your-domain.com - backend.your-domain.com domain name and extension, and optionally a subdomain. - your-domain.com - backend.your-domain.com
</Banner> </Banner>

4
docs/plugins/overview.mdx
View File

@@ -20,12 +20,12 @@ Writing plugins is no more complex than writing regular JavaScript. If you know
- Automatically sync data from a specific collection to HubSpot or a similar CRM when data is added or changes - Automatically sync data from a specific collection to HubSpot or a similar CRM when data is added or changes
- Add password-protection functionality to certain documents - Add password-protection functionality to certain documents
- Add a full ecommerce backend to any Payload app - Add a full e-commerce backend to any Payload app
- Add custom reporting views to Payload's admin panel - Add custom reporting views to Payload's admin panel
- Encrypt specific collections' data - Encrypt specific collections' data
- Add a full form builder implementation - Add a full form builder implementation
- Integrate all `upload`-enabled collections with a third-party file host like S3 or Cloudinary - Integrate all `upload`-enabled collections with a third-party file host like S3 or Cloudinary
- Add custom routes or GraphQL queries / mutations with any type of custom functionality that you can think of - Add custom endpoints or GraphQL queries / mutations with any type of custom functionality that you can think of
### How to install plugins ### How to install plugins

2
docs/rest-api/overview.mdx
View File

@@ -10,7 +10,7 @@ keywords: rest, api, documentation, Content Management System, cms, headless, ja
A fully functional REST API is automatically generated from your Collection and Global configs. A fully functional REST API is automatically generated from your Collection and Global configs.
</Banner> </Banner>
All Payload API routes are mounted prefixed to your config's `routes.api` URL segment (default: `/api`). All Payload API routes are mounted and prefixed to your config's `routes.api` URL segment (default: `/api`).
**REST query parameters:** **REST query parameters:**

2
docs/typescript/generating-types.mdx
View File

@@ -6,7 +6,7 @@ desc: Generate your own TypeScript interfaces based on your collections and glob
keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, express keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, express
--- ---
While building your own custom functionality into Payload, like plugins, hooks, access control functions, custom routes, GraphQL queries / mutations, or anything else, you may benefit from generating your own TypeScript types dynamically from your Payload config itself. While building your own custom functionality into Payload, like plugins, hooks, access control functions, custom views, GraphQL queries / mutations, or anything else, you may benefit from generating your own TypeScript types dynamically from your Payload config itself.
### Types generation script ### Types generation script

2
docs/typescript/overview.mdx
View File

@@ -20,7 +20,7 @@ It's also possible to set up a TypeScript project from scratch. We plan to write
## Using Payload's Exported Types ## Using Payload's Exported Types
Payload exports a number of types that you may find useful while writing your own plugins, hooks, access control functions, custom routes, GraphQL queries / mutations, or anything else. Payload exports a number of types that you may find useful while writing your own plugins, hooks, access control functions, custom views, GraphQL queries / mutations, or anything else.
##### Config Types ##### Config Types