Skip to content

Commit a212cde

Browse files
authored
fix(next): supports root document view overrides as separate from default edit view (#7673)
## Description We've since lost the ability to override the document view at the root-level. This was a feature that made it possible to override _the entire document routing/view structure_, including the document header/tabs and all nested routes within, i.e. the API route/view, the Live Preview route/view, etc. This is distinct from the "default" edit view, which _only_ targets the component rendered within the "edit" tab. This regression was introduced when types were simplified down to better support "component paths" here: #7620. The `default` key was incorrectly used as the "root" view override. To continue to support stricter types _and_ root view overrides, a new `root` key has been added to the `views` config. You were previously able to do this: ```tsx import { MyComponent } from './MyComponent.js' export const MyCollection = { // ... admin: { views: { Edit: MyComponent } } } ``` This is now done like this: ```tsx export const MyCollection = { // ... admin: { views: { edit: { root: { Component: './path-to-my-component.js' } } } } } ``` Some of the documentation was also incorrect according to the new component paths API. - [x] I have read and understand the [CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md) document in this repository. ## Type of change - [x] Bug fix (non-breaking change which fixes an issue) - [x] This change requires a documentation update ## Checklist: - [x] Existing test suite passes locally with my changes - [x] I have made corresponding changes to the documentation
1 parent 4f323a3 commit a212cde

File tree

5 files changed

+290
-256
lines changed

5 files changed

+290
-256
lines changed

docs/admin/views.mdx

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ For more granular control, pass a configuration object instead. Payload exposes
5353

5454
| Property | Description |
5555
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
56-
| **`Component`** \* | Pass in the component that should be rendered when a user navigates to this route. |
56+
| **`Component`** \* | Pass in the component path that should be rendered when a user navigates to this route. |
5757
| **`path`** \* | Any valid URL path or array of paths that [`path-to-regexp`](https://www.npmjs.com/package/path-to-regex) understands. |
5858
| **`exact`** | Boolean. When true, will only match if the path matches the `usePathname()` exactly. |
5959
| **`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 pathname. |
@@ -111,7 +111,20 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
111111
components: {
112112
views: {
113113
edit: {
114-
Component: '/path/to/MyCustomEditView', // highlight-line
114+
root: {
115+
Component: '/path/to/MyCustomEditView', // highlight-line
116+
}
117+
// other options include:
118+
// default
119+
// versions
120+
// version
121+
// api
122+
// livePreview
123+
// [key: string]
124+
// See "Document Views" for more details
125+
},
126+
list: {
127+
Component: '/path/to/MyCustomListView',
115128
}
116129
},
117130
},
@@ -123,7 +136,7 @@ _For details on how to build Custom Views, see [Building Custom Views](#building
123136

124137
<Banner type="warning">
125138
<strong>Note:</strong>
126-
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
139+
The `root` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `edit.default` key instead.
127140
</Banner>
128141

129142
The following options are available:
@@ -152,18 +165,29 @@ export const MyGlobalConfig: SanitizedGlobalConfig = {
152165
admin: {
153166
components: {
154167
views: {
155-
edit: '/path/to/MyCustomEditView', // highlight-line
168+
edit: {
169+
root: {
170+
Component: '/path/to/MyCustomEditView', // highlight-line
171+
}
172+
// other options include:
173+
// default
174+
// versions
175+
// version
176+
// api
177+
// livePreview
178+
// [key: string]
179+
},
156180
},
157181
},
158182
},
159-
})
183+
}
160184
```
161185

162186
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
163187

164188
<Banner type="warning">
165189
<strong>Note:</strong>
166-
The `Edit` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `Edit.Default` key instead.
190+
The `root` property will replace the _entire_ Edit View, including the title, tabs, etc., _as well as all nested [Document Views](#document-views)_, such as the API, Live Preview, and Version views. To replace only the Edit View precisely, use the `edit.default` key instead.
167191
</Banner>
168192

169193
The following options are available:
@@ -199,25 +223,26 @@ export const MyCollectionOrGlobalConfig: SanitizedCollectionConfig = {
199223
},
200224
},
201225
},
202-
})
226+
}
203227
```
204228

205229
_For details on how to build Custom Views, see [Building Custom Views](#building-custom-views)._
206230

207231
<Banner type="warning">
208232
<strong>Note:</strong>
209-
If you need to replace the _entire_ Edit View, including _all_ nested Document Views, use the `Edit` key itself. See [Custom Collection Views](#collection-views) or [Custom Global Views](#global-views) for more information.
233+
If you need to replace the _entire_ Edit View, including _all_ nested Document Views, use the `root` key. See [Custom Collection Views](#collection-views) or [Custom Global Views](#global-views) for more information.
210234
</Banner>
211235

212236
The following options are available:
213237

214238
| Property | Description |
215239
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
216-
| **`default`** | The Default view is the primary view in which your document is edited. |
217-
| **`versions`** | The Versions view is used to view the version history of a single document. [More details](../versions). |
218-
| **`version`** | The Version view is used to view a single version of a single document for a given collection. [More details](../versions). |
219-
| **`api`** | The API view is used to display the REST API JSON response for a given document. |
220-
| **`livePreview`** | The LivePreview view is used to display the Live Preview interface. [More details](../live-preview). |
240+
| **`root`** | The Root View overrides all other nested views and routes. No document controls or tabs are rendered when this key is set. |
241+
| **`default`** | The Default View is the primary view in which your document is edited. It is rendered within the "Edit" tab. |
242+
| **`versions`** | The Versions View is used to navigate the version history of a single document. It is rendered within the "Versions" tab. [More details](../versions). |
243+
| **`version`** | The Version View is used to edit a single version of a document. It is rendered within the "Version" tab. [More details](../versions). |
244+
| **`api`** | The API View is used to display the REST API JSON response for a given document. It is rendered within the "API" tab. |
245+
| **`livePreview`** | The LivePreview view is used to display the Live Preview interface. It is rendered within the "Live Preview" tab. [More details](../live-preview). |
221246

222247
### Document Tabs
223248

0 commit comments

Comments
 (0)