What are Visual Data Previews?

Visual Data Previews are a way for your website's JavaScript to read a file's data as it changes in the Visual Editor using the v0 Visual Editor API.

When you open a file in the Visual Editor, CloudCannon loads your webpage preview inside an iframe with its own separate window, and installs the v0 API on that window as an object named CloudCannon. Once your code calls enableEvents(), CloudCannon dispatches an event on document whenever the open file changes, and the webpage preview in the Visual Editor re-renders with the new values from the CloudCannon object.

When you open a file in the Visual Editor, CloudCannon matches the source file to an output file from your most recent successful build. The output file becomes the webpage preview. If CloudCannon doesn't automatically find the correct output file, you can correct it by adding the url to each Collection. For more information, please read our documentation on what an output file is.

The load and update events#

The diagram below shows the sequence the rest of this article describes.

sequenceDiagram
  participant Page as Your page
  participant CC as CloudCannon
  CC->>Page: cloudcannon:load
  Page->>CC: enableEvents()
  Note over CC: The open file changes
  CC->>Page: cloudcannon:update
  Page->>CC: value()
  CC-->>Page: The latest data
  Note over Page: Your page re-renders

Visual Data Previews use two events, both dispatched on the document object of your previewed page:

• cloudcannon:load — fires as soon as the API is ready. The CloudCannon object is already assigned to window by the time this event fires, so a script that runs late can read window.CloudCannon directly instead of waiting for the event.
• cloudcannon:update — fires after each change to the file you have open, including changes made in the sidebar rather than on the page. Edits that arrive in quick succession, such as typing, are throttled to one event every 50 milliseconds rather than one per keystroke.

Both events carry a detail object holding CloudCannon, the v0 API object, and CloudCannonAPI, the router that serves both versions. The property is detail, singular: e.details is undefined.

Turning on updates#

cloudcannon:update does not fire until something calls enableEvents() on the CloudCannon object. Until then, your page receives the load event and nothing else.

Call enableEvents() once, in your cloudcannon:load handler.

For the v1 equivalent, please read our documentation on listening for changes with the Visual Editor API.

Reading and writing data#

cloudcannon:update tells you that something changed. Two methods on the CloudCannon object cover reading and writing a value.

value() returns a promise resolving to the file's structured data. For a page with front matter, that is the front matter; it does not return the file's body. value() works on every Site: where your Site has migrated to Unified Configuration or has the Enable live configuration and data reloading flag enabled, CloudCannon reads the data live, and where it has neither, CloudCannon reads from the copy of the file it has downloaded for your editing session. For more information, please read our documentation on the Unified Configuration flags.

set() writes a value into the file you have open, which is how a control you built on the page writes back.

For the v1 equivalents, please read our documentation on reading and writing data with the Visual Editor API.

Visual Data Previews for your stack#

If your page is built with React, Vue, or Svelte, start from its connector article: please read our documentation on using Visual Data Previews with React, using Visual Data Previews with Vue, or using Visual Data Previews with Svelte. Each wraps the event handling in a package, so you do not write it yourself.

For the events and the CloudCannon object directly, please read our documentation on using Visual Data Previews with vanilla JavaScript. The connectors wrap that same pattern, so this is also the page to read when one of them does not behave as you expect.

Bookshop generates this same event handling as part of rendering your components, so you do not write it yourself: please read our documentation on using Visual Data Previews with Bookshop.

To mark up which elements on your page correspond to which data, rather than to receive the data itself, please read our documentation on what Visual Data Bindings are.