Two-way content sync
The Netlify Visual Editor stores content back to the appropriate source, while also listening for changes from each source.
The visual editor provides a two-way content-syncing mechanism between all of your content sources. It enables your editors to make changes using the visual editor, while also listening for changes in the content source to ensure you’re previewing the most recent draft content at all times.
# Content flows for visual editor
Understanding the content flows requires prerequisite knowledge on the mechanisms at work while content is being updated.
# Development processes
As you may have learned in How the visual editor works, running Visual Editor in local development mode means running two processes:
- Site Development Server: The server that you would typically run while working on your site locally.
- Visual Editor Dev: The process running on your machine that enables you to run Visual Editor while in development.
# Visual Editor dev application
Although there is some intricacy and nuance in the various components of Visual Editor application, it’s most important to understand the following points:
- Editing controls (everything that isn't the preview of your website) are being run from Visual Editor application (create.netlify.com).
- Visual Editor Dev launches a local server (on port
8090) that combines your development server, along with a script to enable visual editing, and some server-side functionality for storing and retrieving content. (This is the vital piece in content-updating flows shown below.) - The preview is just an
<iframe>loading the content of localhost:8090.
# Differences with cloud setup
The flows we'll show throughout this document assume you're working in local development. Thus, the critical piece is labeled as Stackbit Dev (Visual Editor Dev).
To translate this to how content is updated with the cloud setup (not local development mode), replace Visual Editor Dev with a virtual container running in the cloud. The process itself is nearly identical.
# Work with draft content
To ensure that editors working concurrently see the same content at the same time, Visual Editor relies on a two-way content sync mechanism that stores all changes back to the source, while constantly listening for updates made to the source.
As a result, every editor works with content as it exists in the most recent draft state in the source of truth.
Need a different workflow?
If you have a need to work with content in some other way, we can likely accommodate your workflow. Send us a message to learn more.
# Content editing methods
Before we get into the flows, let's look at the content-editing methods with Visual Editor:
- Content Editor: A more traditional CMS-like method for editing any one of your content models without the preview context.
- Page Editor: Field-based editing within the context of a specific page, and with real-time updates to the preview.
- Inline Editing: Editing inline and in-context using highlights on the preview.
- Source Editing: Using some other method to update content at the source.
Each of these actions prompts a specific content update flow that is explained in further detail below.
# Content editor
The content editor is the most traditional means of editing content with Visual Editor. It prompts the simplest update flow, because there is no preview to update. Learn more about the content editor.
# Page editor
The page editor is a form-based editor, but appears within the context of the active page in the preview window. The content flow here is slightly more advanced, as it requires that the preview also be updated when the content changes at the source.
# Inline editing
Inline editing is the most advanced form of editing. It enables editors to click on content within the preview and edit in place. Visual Editor must then update the content in the page and content editor, while also updating the source and the preview (after the highlight is blurred).
# Source editing
Finally, you're always free to edit content outside the context of Visual Editor. For example, if you are storing content in Contentful, you can still update content in Contentful. Visual Editor listens for content changes and pulls them into each of the editing techniques above in real time.
Some content sources also have other means of updating content, such as through an API. Visual Editor will also pick up these changes to reflect the most recent draft content in the preview and editor panels.
# Content sync flows
Let's look at Visual Editor’s standard two-way content syncing mechanism, which saves content back to the source, while also listening for changes made from other Visual Editor users or content updates made directly to the source.
This method serves both the standard content editor and page editor, with a slight difference, as noted below.
# Send changes to the source
Regardless of whether you're working with the content editor or page editor, here's what happens when you make a change to a form field value in Visual Editor while working locally:
- Visual Editor notifies Visual Editor dev server of the content change.
- Visual Editor Dev updates the appropriate content in the content source.
- Visual Editor app notifies Visual Editor script (via
postMessageto the<iframe>), which leads to automatically updating content on your site, optimized for your chosen site framework.
There's a bit of detail missing from this process, which we'll fill in below.
# Reactive content updates
Visual Editor Dev also listens for content changes coming from the content source. This is how the values within both the form fields (content and page editing) and the preview (page editing only) stay up to date.
When content is updated, whether by you, another Visual Editor user, or at the source, here's what happens:
- Visual Editor Dev identifies the update from the content source (via polling).
- Visual Editor Dev notifies Visual Editor app of the content change. The app updates the appropriate field values.
- Like above, Visual Editor app notifies the preview's visual editing script of the change, leading to updated content on the page.
# Detailed content flow
With that, let's break each of these steps up and look at the entire flow of a content update, originating with a change to a form field.
- A change is made to a form field. Visual Editor app notifies Visual Editor Dev of the change.
- Visual Editor Dev's CMS utilities update content in the content source.
- Visual Editor Dev's content listener polls the content source for changes. After content is updated in the source, Visual Editor Dev retrieves the new content.
- Visual Editor Dev sends the updated content to Visual Editor app.
- The app notifies Visual Editor script (in the preview
<iframe>) of the change (viapostMessage). The script triggers an efficient content reload for your framework (as described in automatic content reload, below). - Your dev server reacts to this trigger by retrieving content from the content source. This is the code you've written to fetch and render content for your pages and components.
- After retrieving that content, your dev server reloads the DOM, making the updated content appear in the
<iframe>preview.
# Work with file-based content
If using local files as the content source (Git CMS), the content flow is similar, but the effect is slightly different:
- Local Development: Files are changed directly by Visual Editor Dev, but left uncommitted on your local machine.
- Visual Editor Project: Every content change becomes a Git commit on the working branch, and is then pushed to the content source (e.g. GitHub).
# Automatic content reload
When Visual Editor updates the content on your page (#5 in the graphic above), this is what we call automatic content reloading.
How exactly this works is determined by the ssgName configuration property. For example, if using Next.js, Visual Editor knows to call router.replace() to reload the content without a full page reload.
For custom usage or frameworks not yet supported, you can also override this behavior by listening for an event sent by Visual Editor when content updates. Learn more about automatic content reload.
# Inline editing content flow
When a change is made inline (rather than a form field), the content flow is nearly identical to the detailed flow discussed above.
The only difference (marked as * above) comes at the beginning of the flow. The visual editing script notifies Visual Editor app about the change (again via an iframe message). The rest of the flow then continues as before.
# DOM reloading
Step #7 may feel odd in this case, given that we shouldn't need to update the preview when the content has already been updated.
But there are two reasons why this is necessary:
- Visual Editor doesn't know how to render all changes. Inline text may seem easy, but if the change was to add a button — Visual Editor can prompt the content change, but needs to wait to react to how your site handles the rendering of that change.
- If another user is editing the site, we also want to show that content has changed, so that they can continue working with the most updated content.
Did you find this doc useful?
Your feedback helps us improve our docs.