Live Preview

[jacobsfletch]

We need to build a Live Preview feature into Payload so that editors can view updates on their front-end in real-time as they edit fields, without needing to save the document or navigate away from the admin dashboard. This will render a new "Preview" component directly alongside the document which will be used to render a website with live data on-the-fly.

How it will work:

Your website will be served within an iframe directly in the admin panel. As you make changes to your document, those changes are broadcast to the iframe via a postMessage event. Your website will then receive the event and re-render itself with the new data. Exactly how this is achieved will differ across front-end frameworks, but Payload will provide basic utility functions for the most popular ones, starting with Next.js.

What needs to be done:

The feature itself is relatively simple, but adjusting the admin UI to create extra space is not. Since the preview iframe will need to take up quite a lot of visual real estate, there is not enough room for everything that our admin UI requires. So to mitigate this, we may need to drastically rearrange the UI to maximize horizontal space. Simply collapsing the sidebar will not be enough. Instead, the sidebar will likely be replaced with a header nav (pending design exploration).

Other requirements:

• Migrate sidebar to header (described above)
• Make sure live preview works with any frontend
• Include typical preview controls like dimensions, zoom, auto-update, etc
• Allow users to hide the fields so they can view their preview at full width
• Establish a pattern for multiple extensible and swappable “views”
• Make the UI NICE—use a border-less iframe, consider white-on-white, etc

Huge shoutout to @jpeiniger, @dkirchhof, @DennisSnijder, and their whole team for kickstarting this work with their visual editor plugin. It's received some great reception and will be looked to for inspiration as we integrate this feature into core.

Related: #997

Update from @jacobsfletch 8/23/2023

We've begun redesigning the admin UI to accommodate Live Preview as well as the preview interface itself. There's a separate discussion around that (including images 🤩) which can be found here: #3217. Feel free to jump into the conversation there as well.

Update from @jacobsfletch 9/21/2023

Admin 2.0 is done 🎉
and there's a POC of Live Preview demonstrated here: #3061 (comment)

[jpeiniger]

Looking forward to this becoming a core feature ❤️

[paulpopus]

Can we make this preview window popout-able?

Use case: On a laptop, you have a very limited amount of screen space and one of the most common usability features is alt-tabbing or virtual desktops so you can quickly switch between windows; the other one I use a lot is picture in picture.

Technical solutions:

1. Eventually, PIP support https://developer.chrome.com/docs/web-platform/document-picture-in-picture/
2. Until then, a button to open in a new tab/window? I can resize and pin that myself

[jacobsfletch]

@paulpopus this is 🔥

[matthijs166]

Very cool! I think it needs to be by default in the same window

[dkirchhof]

The extension of pip sounds great :)

[dkirchhof]

Just a quick test 🙃

visual-editor.webm

[matthijs166]

Yeah UI is indeed the big question. I think we need to draw some inspiration from some other visual editors like: Webflow, Elementor, Wix etc..

It would also incredibly beneficial to send back the data within the live preview, allowing developers to create their own editing tools on top of it, for instance:

1. A title field defined in Payload as "Example" would be sent to the live preview, rendering the title as "Example"
2. The developer can then wrap the title inside an edit component, allowing the admin to click on the title and modify it to say "Example Test"
3. The updated title is then sent back (by the edit component) from the live preview to Payload, effectively saving the edit.

By following this approach, developers can seamlessly integrate the live preview functionality into their applications, empowering users to make real-time changes without having to switch between different editing modes. This enhances the overall user experience and simplifies the editing process.

There is also the option to support/create the necessary edit components, but that's framework dependent, better to be left to the community.

Other thought is that we draw inspiration from https://vercel.com/docs/workflow-collaboration/visual-editing and use source maps to map the data and extend it with an overlay.

[jacobsfletch]

Other thought is that we draw inspiration from https://vercel.com/docs/workflow-collaboration/visual-editing and use source maps to map the data and extend it with an overlay.

Hey @matthijs166 check this out 😉 https://payloadcms.com/docs/integrations/vercel-visual-editing

Whether its with Vercel or not, this is 100% the end-game. We will absolutely be building tools so we can send data both ways. It's much more tricky to go front-end->Payload though in a nice and elegant way that doesn't require serious overhaul of your components, i.e. Rich Text.

[dkirchhof]

Do you plan to allow the user to edit everything or just text / richt text fields?
Just remembered the pain in gutenberg where we have to define all components for the frontend and backend twice, because the styling doesn't match 100% etc.

I can imagine that editing plain text fields (for example by using the contenteditable attribute) would be fine.

For the preview window, I implemented the first messages, which will be send from the frontend to the cms.
This channel could be used to send changes from the iframe / window / pip back to the cms.
I have some ideas in mind, how it could work, but I think you are further than I think, right?

[jacobsfletch]

Just remembered the pain in gutenberg where we have to define all components for the frontend and backend twice, because the styling doesn't match 100% etc.

Yea that's the tricky part here @dkirchhof, there needs to be as little manual effort as possible. This is why Vercel Visual Editing works well, they render hidden, encoded values into the front-end so that there is little to no integration needed. When these values are detected on the front-end, they overlay their own proprietary editor overtop so you can easily navigate back and forth between the CMS and the front-end. BUT this is not true visual editing, because as of now nothing is marked contenteditable (this will likely change in the future, if I had to guess). Payload will likely provide it's own tools for this, with text being relatively simply but rich text being extremely complex.

[franknoel]

@jacobsfletch Are you planning to release Vercel Visual Editing integration for non-enterprise customers?

[dkirchhof]

And another test:
Will playing around with a solution with less effort for the frontend implementation (like in vercels visual editing feature).

visual-editor_select_input_2.mp4

[jpeiniger]

love it!

[dkirchhof]

And the other way around (select input => scroll to element in preview and highlight it):

visual-editor_select_input_back_and_forth.mp4

[coxmi]

Love it!

It'd be interesting to know how Vercel's visual editor deals with more complicated data types than string, or translated/processed values.
I'd assume this will always need some form of manual data wrangling, since a date field could be "X minutes ago", ISO8601, a variety of international formats, and translated/processed values will be unpredictable.

[denolfe]

We'll be discussing Live Preview and Admin UI improvements today in Discord. https://twitter.com/payloadcms/status/1694047842560573569

[jacobsfletch]

Admin 2.0 has been completed! This has unlocked some major progress to Live Preview. Not quite ready to open a PR for this yet, but you can follow along this branch for updates. Here's a sneak peak 😏:

payload-live-preview.mp4

[dkirchhof]

When I implemented the windowed preview in our plugin, I added a post message "channel" which is used to send message from the frontend back to payload. This is used to notify the CMS that the frontend is ready to receive updates. Payload will send immediately the current document afterwards.

This is just to prevent the "loading..." message before any changes made in the editor.

[jacobsfletch]

@dkirchhof yea 👍 that is exactly what the useLivePreview hook is doing currently here: https://github.com/payloadcms/payload/pull/3382/files#diff-b32ba70226aa90f43eda014925ed6d5bf5ab42bb54567f6cf6b5cef583b046f7R33

That loading message is actually related to the popup window not being ready before the initial post message is broadcast to it here: https://github.com/payloadcms/payload/pull/3382/files. I just wanted to share this before getting in the weeds with a fix for this.

Also, I did just draft a PR to make it easier to follow along: #3382

[jacobsfletch]

Quick update here, Live Preview has been scaffolded out at a high level: #3382. We're mainly through UI at this point (still a lot of refinements to be made here though). But we also have a lot of the patterns in place to begin finishing the API portion of this work, i.e. the useLivePreview hook. It's going to be a big week to get this finished out ahead of 2.0. I continue to post updates as I have them!

[jpeiniger]

That's awesome @jacobsfletch. Looking forward to it, as the API portion at the moment is a tricky part in the current plugin. E.g. getting relations inside of richtext and stuff like this. 😅

[franknoel]

Incredible work @jacobsfletch 👏 Can't wait to use it! One question that I always had about this feature is if it will work in a multiple-tenant project with different domains.

[jacobsfletch]

@franknoel hmmm this seems possible, we would just need to swap out the iframe src depending on the value the document's tenant. I can dive deeper into this some time, good call 👍

[jacobsfletch]

Big update here prior to the weekend: the data side of things is mostly complete! Andddd its written in a way that is very composable. This is the part that I'm most excited about. This will enable us to support any front-end framework, not just React. Essentially, we've abstracted the core functions out of the useLivePreview hook (like subscribe and unsubscribe) so that they can be integrated anywhere (like Vue or Svelte...or plain JS). I will be writing documentation around all of this, but you will be able to install a standalone dependency into your app that is per framework, starting with @payloadcms/live-preview-react. Here's a recap of the work that went into this:

• Builds fieldSchemaToJSON utility
• Handles live preview data
• Builds live preview JavaScript and React SDKs
• Builds a more complex live preview test app
• Supports live preview url as function
• And a few other misc fixes in between

This might also be the last update I make to this thread. This feature will be rolling out in beta next week! 😱 🚀

[jpeiniger]

Great work! Looking forward to playing around on Monday. 💪

[tiagordebarros]

Congratulations! Fantastic work!🚀

[robinscholz]

@jacobsfletch Is it correct to assume, that there is currently no way to enable live preview for data coming from custom endpoints? It seems like the feature is tightly coupled to the internal API, right?