Skip to content

Commit 8fe6ffd

Browse files
jacobsfletchjacobsfletch
authored
feat(examples): adds custom components example (#8162)
1 parent 0118bce commit 8fe6ffd

File tree

95 files changed

+8798
-13
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

95 files changed

+8798
-13
lines changed

‎docs/admin/views.mdx‎

Lines changed: 47 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -31,16 +31,52 @@ const config = buildConfig({
3131
admin: {
3232
components: {
3333
views: {
34-
dashboard: {
35-
Component: '/path/to/MyCustomDashboardView#MyCustomDashboardViewComponent', // highlight-line
34+
customView: {
35+
Component: '/path/to/MyCustomView#MyCustomView', // highlight-line
36+
path: '/my-custom-view',
3637
}
3738
},
3839
},
3940
},
4041
})
4142
```
4243

43-
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
44+
Your Custom Root Views can optionally use one of the templates that Payload provides. The most common of these is the Default Template which provides the basic layout and navigation. Here is an example of what that might look like:
45+
46+
```tsx
47+
import type { AdminViewProps } from 'payload'
48+
49+
import { DefaultTemplate } from '@payloadcms/next/templates'
50+
import { Gutter } from '@payloadcms/ui'
51+
import React from 'react'
52+
53+
export const MyCustomView: React.FC<AdminViewProps> = ({
54+
initPageResult,
55+
params,
56+
searchParams,
57+
}) => {
58+
return (
59+
<DefaultTemplate
60+
i18n={initPageResult.req.i18n}
61+
locale={initPageResult.locale}
62+
params={params}
63+
payload={initPageResult.req.payload}
64+
permissions={initPageResult.permissions}
65+
searchParams={searchParams}
66+
user={initPageResult.req.user || undefined}
67+
visibleEntities={initPageResult.visibleEntities}
68+
>
69+
<Gutter>
70+
<h1>Custom Default Root View</h1>
71+
<br />
72+
<p>This view uses the Default Template.</p>
73+
</Gutter>
74+
</DefaultTemplate>
75+
)
76+
}
77+
```
78+
79+
_For details on how to build Custom Views, including all available props, see [Building Custom Views](#building-custom-views)._
4480

4581
The following options are available:
4682

@@ -133,7 +169,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
133169
}
134170
```
135171

136-
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
172+
_For details on how to build Custom Views, including all available props, see [Building Custom Views](#building-custom-views)._
137173

138174
<Banner type="warning">
139175
<strong>Note:</strong>
@@ -184,7 +220,7 @@ export const MyGlobalConfig: SanitizedGlobalConfig = {
184220
}
185221
```
186222

187-
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
223+
_For details on how to build Custom Views, including all available props, see [Building Custom Views](#building-custom-views)._
188224

189225
<Banner type="warning">
190226
<strong>Note:</strong>
@@ -227,7 +263,7 @@ export const MyCollectionOrGlobalConfig: SanitizedCollectionConfig = {
227263
}
228264
```
229265

230-
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
266+
_For details on how to build Custom Views, including all available props, see [Building Custom Views](#building-custom-views)._
231267

232268
<Banner type="warning">
233269
<strong>Note:</strong>
@@ -312,13 +348,11 @@ Your Custom Views will be provided with the following props:
312348

313349
| Prop | Description |
314350
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
315-
| **`user`** | The currently logged in user. |
316-
| **`locale`** | The current [Locale](../configuration/localization) of the [Admin Panel](./overview). |
317-
| **`navGroups`** | The grouped navigation items according to `admin.group` in your [Collection Config](../collections/overview) or [Global Config](../globals/overview). |
318-
| **`params`** | An object containing the [Dynamic Route Parameters](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes). |
319-
| **`permissions`** | The permissions of the currently logged in user. |
320-
| **`searchParams`** | An object containing the [Search Parameters](https://developer.mozilla.org/docs/Learn/Common_questions/What_is_a_URL#parameters). |
321-
| **`visibleEntities`** | The current user's visible entities according to your [Access Control](../access-control/overview). |
351+
| **`initPageResult`** | An object containing `req`, `payload`, `permissions`, etc. |
352+
| **`clientConfig`** | The Client Config object. [More details](../components#accessing-the-payload-config). |
353+
| **`importMap`** | The import map object. |
354+
| **`params`** | An object containing the [Dynamic Route Parameters](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes). |
355+
| **`searchParams`** | An object containing the [Search Parameters](https://developer.mozilla.org/docs/Learn/Common_questions/What_is_a_URL#parameters). |
322356

323357
<Banner type="success">
324358
<strong>Reminder:</strong>

‎docs/examples/overview.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Payload provides a vast array of examples to help you get started with your proj
1111
Examples are changing every day, so be sure to check back often to see what new examples have been added. If you have a specific example you would like to see, please feel free to start a new [Discussion](https://github.com/payloadcms/payload/discussions) or open a new [PR](https://github.com/payloadcms/payload/pulls) to add it yourself.
1212

1313
- [Auth](https://github.com/payloadcms/payload/tree/main/examples/auth)
14+
- [Custom Components](https://github.com/payloadcms/payload/tree/main/examples/custom-components)
1415
- [Custom Server](https://github.com/payloadcms/payload/tree/main/examples/custom-server)
1516
- [Draft Preview](https://github.com/payloadcms/payload/tree/main/examples/draft-preview)
1617
- [Email](https://github.com/payloadcms/payload/tree/main/examples/email)

‎examples/custom-components/.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
DATABASE_URI=mongodb://127.0.0.1/payload-example-custom-fields
2+
PAYLOAD_SECRET=PAYLOAD_CUSTOM_FIELDS_EXAMPLE_SECRET_KEY
3+
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000

‎examples/custom-components/.eslintrc.cjs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module.exports = {
2+
root: true,
3+
extends: ['@payloadcms'],
4+
}

‎examples/custom-components/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
build
2+
dist
3+
node_modules
4+
package-lock.json
5+
.env

‎examples/custom-components/.swcrc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"$schema": "https://json.schemastore.org/swcrc",
3+
"sourceMaps": true,
4+
"jsc": {
5+
"target": "esnext",
6+
"parser": {
7+
"syntax": "typescript",
8+
"tsx": true,
9+
"dts": true
10+
},
11+
"transform": {
12+
"react": {
13+
"runtime": "automatic",
14+
"pragmaFrag": "React.Fragment",
15+
"throwIfNamespace": true,
16+
"development": false,
17+
"useBuiltins": true
18+
}
19+
}
20+
},
21+
"module": {
22+
"type": "es6"
23+
}
24+
}

‎examples/custom-components/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Payload Custom Components Example
2+
3+
This example demonstrates how to use Custom Components in [Payload](https://github.com/payloadcms/payload) Admin Panel. This example includes custom components for every field type available in Payload, including both server and client components. It also includes custom views, custom nav links, and more.
4+
5+
## Quick Start
6+
7+
To spin up this example locally, follow these steps:
8+
9+
1. Clone this repo
10+
1. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
11+
12+
> \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
13+
14+
1. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
15+
- Press `y` when prompted to seed the database
16+
1. `open http://localhost:3000` to access the home page
17+
1. `open http://localhost:3000/admin` to access the admin panel
18+
- Login with email `demo@payloadcms.com` and password `demo`
19+
20+
## How it works
21+
22+
### Collections
23+
24+
See the [Collections](https://payloadcms.com/docs/configuration/collections) docs for details on how to extend any of this functionality.
25+
26+
- #### Users
27+
28+
The `users` collection is auth-enabled which provides access to the admin panel.
29+
30+
For additional help with authentication, see the official [Auth Example](https://github.com/payloadcms/payload/tree/main/examples/auth/cms#readme) or the [Authentication](https://payloadcms.com/docs/authentication/overview#authentication-overview) docs.
31+
32+
- #### Fields
33+
34+
The `fields` collection contains every field type available in Payload, each with custom components filled in every available "slot", i.e. `admin.components.Field`, `admin.components.Label`, etc. There are two of every field, one for server components, and the other for client components. This pattern shows how to use custom components in both environments, no matter which field type you are using.
35+
36+
- #### Views
37+
38+
The `views` collection demonstrates how to add collection-level views, including the default view and custom tabs.
39+
40+
- #### Root Views
41+
42+
The `root-views` collection demonstrates how to add a root document-level view to the admin panel.
43+
44+
## Questions
45+
46+
If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/payload) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions).

‎examples/custom-components/next-env.d.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/// <reference types="next" />
2+
/// <reference types="next/image-types/global" />
3+
4+
// NOTE: This file should not be edited
5+
// see https://nextjs.org/docs/basic-features/typescript for more information.

‎examples/custom-components/next.config.mjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { withPayload } from '@payloadcms/next/withPayload'
2+
3+
/** @type {import('next').NextConfig} */
4+
const nextConfig = {
5+
// Your Next.js config here
6+
}
7+
8+
export default withPayload(nextConfig)

‎examples/custom-components/package.json‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"name": "payload-example-custom-fields",
3+
"version": "1.0.0",
4+
"description": "An example of custom fields in Payload.",
5+
"license": "MIT",
6+
"type": "module",
7+
"scripts": {
8+
"_dev": "cross-env NODE_OPTIONS=--no-deprecation && pnpm generate:importmap && next dev",
9+
"build": "cross-env NODE_OPTIONS=--no-deprecation next build",
10+
"dev": "cross-env NODE_OPTIONS=--no-deprecation && pnpm generate:importmap && pnpm seed && next dev --turbo",
11+
"generate:importmap": "payload generate:importmap",
12+
"generate:schema": "payload-graphql generate:schema",
13+
"generate:types": "payload generate:types",
14+
"payload": "cross-env NODE_OPTIONS=--no-deprecation payload",
15+
"seed": "npm run payload migrate:fresh",
16+
"start": "cross-env NODE_OPTIONS=--no-deprecation next start"
17+
},
18+
"dependencies": {
19+
"@payloadcms/db-mongodb": "3.0.0-beta.102",
20+
"@payloadcms/next": "3.0.0-beta.102",
21+
"@payloadcms/richtext-lexical": "3.0.0-beta.102",
22+
"@payloadcms/ui": "3.0.0-beta.102",
23+
"cross-env": "^7.0.3",
24+
"dotenv": "^8.2.0",
25+
"graphql": "^16.9.0",
26+
"next": "15.0.0-canary.104",
27+
"payload": "3.0.0-beta.102",
28+
"react": "19.0.0-rc-06d0b89e-20240801",
29+
"react-dom": "19.0.0-rc-06d0b89e-20240801"
30+
},
31+
"devDependencies": {
32+
"@payloadcms/graphql": "3.0.0-beta.102",
33+
"@types/react": "npm:types-react@19.0.0-beta.2",
34+
"@types/react-dom": "npm:types-react-dom@19.0.0-beta.2",
35+
"eslint": "^8.57.0",
36+
"eslint-config-next": "15.0.0-canary.146",
37+
"tsx": "^4.7.1",
38+
"typescript": "5.5.2"
39+
},
40+
"engines": {
41+
"node": "^18.20.2 || >=20.9.0"
42+
}
43+
}

0 commit comments

Comments
 (0)