docs: cleans up live preview overview (#7068)
This commit is contained in:
Jacob Fletcher
@@ -2,27 +2,40 @@
|
||||
title: Live Preview
|
||||
label: Overview
|
||||
order: 10
|
||||
desc: With Live Preview you can render your front-end application directly within the Admin panel. Your changes take effect as you type. No save needed.
|
||||
desc: With Live Preview you can render your front-end application directly within the Admin Panel. Your changes take effect as you type. No save needed.
|
||||
keywords: live preview, preview, live, iframe, iframe preview, visual editing, design
|
||||
---
|
||||
|
||||
**With Live Preview you can render your front-end application directly within the Admin panel. As you type, your changes take effect in real-time. No need to save a draft or publish your changes.**
|
||||
With Live Preview you can render your front-end application directly within the [Admin Panel](../admin/overview). As you type, your changes take effect in real-time. No need to save a draft or publish your changes. This works in both [Server-side](./server) as well as [Client-side](./client) environments.
|
||||
|
||||
Live Preview works by rendering an iframe on the page that loads your front-end application. The Admin panel communicates with your app through [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) events. These events are emitted every time a change is made to the document. Your app then listens for these events and re-renders itself with the data it receives. Live Preview works in both server-side as well as client-side environments. See [Front-End](./frontend) for more details.
|
||||
Live Preview works by rendering an iframe on the page that loads your front-end application. The Admin Panel communicates with your app through [`window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) events. These events are emitted every time a change is made to the document. Your app then listens for these events and re-renders itself with the data it receives.
|
||||
|
||||
{/* IMAGE OF LIVE PREVIEW HERE */}
|
||||
|
||||
<Banner type="warning">
|
||||
Live Preview is currently in beta. You may use this feature in production, but please be aware
|
||||
that it is subject to change and may not be fully stable for all use cases. If you encounter any
|
||||
issues, please [report
|
||||
them](https://github.com/payloadcms/payload/issues/new?assignees=jacobsfletch&labels=possible-bug&projects=&title=Live%20Preview&template=1.bug_report.yml)
|
||||
with as much detail as possible.
|
||||
</Banner>
|
||||
|
||||
## Setup
|
||||
|
||||
Setting up Live Preview is easy. You first need to enable it through the `admin.livePreview` property of your Payload config. It takes the following options:
|
||||
Setting up Live Preview is easy. This can be done either globally through the [Root Config](../configuration/overview), or on individual [Collection](../configuration/collections) and [Global](../configuration/globals) configs. Once configured, a new "Live Preview" tab will appear at the top of enabled documents. Navigating to this tab opens the preview window and loads your front-end application.
|
||||
|
||||
To add Live Preview, use the `admin.livePreview` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
// highlight-start
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000', // The URL to your front-end, this can also be a function (see below)
|
||||
collections: ['pages'], // The Collection(s) to enable Live Preview on (Globals are also possible)
|
||||
},
|
||||
// highlight-end
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
|
||||
| Path | Description |
|
||||
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -33,60 +46,47 @@ Setting up Live Preview is easy. You first need to enable it through the `admin.
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
|
||||
Here is a basic example of enabling Live Preview on a `pages` collection:
|
||||
|
||||
```ts
|
||||
// payload.config.ts
|
||||
{
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000', // The URL to your front-end, this can also be a function (see below)
|
||||
collections: ['pages'], // The collections to enable Live Preview on (globals are also possible)
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, you can define the <code>admin.livePreview</code> property on individual collection and global configs. Settings defined here will be merged into the top-level as overrides (if applicable).
|
||||
|
||||
```ts
|
||||
// Collection.ts
|
||||
{
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000',
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once configured, a new "Live Preview" tab will appear at the top of enabled documents. Navigating to this tab opens the preview window and loads your front-end application.
|
||||
<Banner type="warning">
|
||||
<strong>Reminder:</strong>
|
||||
Alternatively, you can define the <code>admin.livePreview</code> property on individual [Collection](../configuration/collections) and [Global](../configuration/globals) configs. Settings defined here will be merged into the top-level as overrides.
|
||||
</Banner>
|
||||
|
||||
### URL
|
||||
|
||||
The `url` property is a string that points to your front-end application. This value is used as the `src` attribute of the iframe rendering your front-end.
|
||||
The `url` property is a string that points to your front-end application. This value is used as the `src` attribute of the iframe rendering your front-end. Once loaded, the Admin Panel will communicate directly with your app through `window.postMessage` events.
|
||||
|
||||
You can also pass a function in order to dynamically format URLs. This function is called with the following arguments:
|
||||
|
||||
| Path | Description |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| **`data`** | The data of the document being edited. This includes changes that have not yet been saved. |
|
||||
| **`documentInfo`** | Information about the document being edited like collection slug. [More details](../admin/hooks#usedocumentinfo). |
|
||||
| **`locale`** | The locale currently being edited (if applicable). [More details](../configuration/localization). |
|
||||
|
||||
Here is an example of using a function that returns a dynamic URL:
|
||||
To set the URL, use the `admin.livePreview.url` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
```ts
|
||||
// payload.config.ts
|
||||
{
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000', // highlight-line
|
||||
collections: ['pages'],
|
||||
},
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Dynamic URLs
|
||||
|
||||
You can also pass a function in order to dynamically format URLs. This is useful for multi-tenant applications, localization, or any other scenario where the URL needs to be generated based on the document being edited.
|
||||
|
||||
To set dynamic URLs, set the `admin.livePreview.url` property in your [Payload Config](../configuration/overview) to a function:
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
// highlight-start
|
||||
url: ({
|
||||
data,
|
||||
documentInfo,
|
||||
@@ -96,13 +96,50 @@ Here is an example of using a function that returns a dynamic URL:
|
||||
}${locale ? `?locale=${locale?.code}` : ''}`, // Localization query param
|
||||
collections: ['pages'],
|
||||
},
|
||||
// highlight-end
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The following arguments are provided to the `url` function:
|
||||
|
||||
| Path | Description |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| **`data`** | The data of the document being edited. This includes changes that have not yet been saved. |
|
||||
| **`documentInfo`** | Information about the document being edited like collection slug. [More details](../admin/hooks#usedocumentinfo). |
|
||||
| **`locale`** | The locale currently being edited (if applicable). [More details](../configuration/localization). |
|
||||
|
||||
### Breakpoints
|
||||
|
||||
The breakpoints property is an array of objects which are used as “device sizes” in the preview window. Each item will render as an option in the toolbar. When selected, the preview window will resize to the exact dimensions specified in that breakpoint. Each breakpoint takes the following properties:
|
||||
The breakpoints property is an array of objects which are used as “device sizes” in the preview window. Each item will render as an option in the toolbar. When selected, the preview window will resize to the exact dimensions specified in that breakpoint.
|
||||
|
||||
To set breakpoints, use the `admin.livePreview.breakpoints` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000',
|
||||
// highlight-start
|
||||
breakpoints: [
|
||||
{
|
||||
label: 'Mobile',
|
||||
name: 'mobile',
|
||||
width: 375,
|
||||
height: 667,
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
},
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
The following options are available for each breakpoint:
|
||||
|
||||
| Path | Description |
|
||||
| --------------- | --------------------------------------------------------------------------- |
|
||||
@@ -113,41 +150,6 @@ The breakpoints property is an array of objects which are used as “device size
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
|
||||
Here is an example of defining breakpoints:
|
||||
|
||||
```ts
|
||||
// payload.config.ts
|
||||
{
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
livePreview: {
|
||||
url: 'http://localhost:3000',
|
||||
breakpoints: [
|
||||
{
|
||||
label: 'Mobile',
|
||||
name: 'mobile',
|
||||
width: 375,
|
||||
height: 667,
|
||||
},
|
||||
{
|
||||
label: 'Tablet',
|
||||
name: 'tablet',
|
||||
width: 768,
|
||||
height: 1024,
|
||||
},
|
||||
{
|
||||
label: 'Desktop',
|
||||
name: 'desktop',
|
||||
width: 1440,
|
||||
height: 900,
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{/* IMAGE OF TOOLBAR HERE */}
|
||||
|
||||
The "Responsive" option is always available in the drop-down and requires no additional configuration. This is the default breakpoint that will be used on initial load. This option styles the iframe with a width and height of `100%` so that it fills the screen at its maximum size and automatically resizes as the window changes size.
|
||||
|
||||
Reference in New Issue
Block a user