Visual Editor API

The Visual Editor API is a JavaScript API for building custom integrations that run inside CloudCannon's Visual Editor. Obtain the API Object, then call its methods to access files, Collections, and Datasets, read and write content, upload files, and build custom integrations. This reference covers the v1 API.

For an introduction and walkthroughs, please read our documentation on what the Visual Editor API is and the Build custom Visual Editor integrations guide. For IDE autocomplete and validation, please read our documentation on using TypeScript with the Visual Editor API.

Getting the API Object#

The API is exposed on window.CloudCannonAPI, a router that hands you a versioned API Object. Call useVersion('v1', true) to get the v1 object:

const api = window.CloudCannonAPI.useVersion('v1', true);

The second argument, preventGlobalInstall, keeps the v1 API Object off the global window.CloudCannon so it can't clash with other integrations that request a different version, such as Bookshop. Pass true unless you have a reason not to.

window.CloudCannonAPI is available whenever a file is open in the Visual Editor. If your script might run before that, listen for the cloudcannon:load event on document and read window.CloudCannonAPI once it fires. For the full initialization pattern, see Initialize the Visual Editor API.

Events#

Several objects let you react to content changes with addEventListener, and stop listening with removeEventListener. Both accept the same two event types:

• change fires when a file is created or updated. event.detail.isNew is true when the file was newly created, and false when an existing file was updated.
• delete fires when a file is removed.

The object you attach the listener to sets its scope. Listening on the API Object reacts to any file across the Site; listening on a Collection or Dataset reacts to any file within it; listening on a File reacts to that one file.

Every event carries event.detail.sourcePath, the path of the file that changed, so you can tell which file triggered it. This is most useful on API Object, Collection, and Dataset listeners, where one listener covers many files. A File listener already targets one known file, so you can read that file directly instead of relying on sourcePath.

api.collection('posts').addEventListener('change', (event) => {
  console.log('A post changed:', event.detail.sourcePath);
});

Remove a listener with removeEventListener when your integration is torn down.

Methods#

The v1 API Object's methods are documented on the API Object page. Return types link to the object pages they produce.

Objects#

The API Object is your entry point: call its methods to reach everything else. Those methods return the objects below, and a File exposes data and content objects. Each is documented on its own page:

• API Object
• Collection
• Dataset
• File
• FileContent
• FileData
• FileMetadata
• TextEditableRegion