Listen for changes with the Visual Editor API

CloudCannon's Visual Editor API exposes change and delete events on the API root, on individual files, and on Collections and Datasets. Add listeners with addEventListener and remove them with removeEventListener when your custom UI or preview is torn down.

This article assumes you know how to initialize the Visual Editor API and access files, Collections, and Datasets. For a complete list of API objects and methods, please read our reference documentation on the Visual Editor API.

Event types and scopes#

You can listen to two types of events using the Visual Editor API: change, which fires when a file in your Site is created or updated, or delete, which fires when a file is deleted. Both use the standard addEventListener and removeEventListener interface from EventTarget.

Each event carries a detail object. Because change fires for both new and updated files, check event.detail.isNew to tell them apart. The value is true when the file was newly created and false when an existing file was updated. Every event also carries event.detail.sourcePath, the path of the file that changed, which is most useful on root, Collection, and Dataset listeners, where one listener covers many files.

You can also attach listeners at multiple levels, depending on how broad or narrow you need your events to be, including root, file, Collection, and Dataset.

Root level events

Calling *.addEventListener() on the API Object allows you to receive events for any change across your entire Site.

const api = window.CloudCannonAPI.useVersion('v1', true);
api.addEventListener('change', (event) => { 
  console.log('Something changed');
  console.log(event.detail.sourcePath); 
  console.log(event.detail.isNew); 
});

File level events

You can listen to a specific file object using *.addEventListener() to receive events for that file only.

const file = api.currentFile(); 

file.addEventListener('change', () => { 
  console.log('Current file changed');
});

file.addEventListener('delete', () => { 
  console.log('Current file was deleted');
});

Collection and Dataset level

Calling *.addEventListener() on a Collection or Dataset allows you to receive events for any file within it.

For more information about how Collections and Datasets work with the Visual Editor API, please read our documentation on listing files, Collections, and Datasets with the Visual Editor API.

const posts = api.collection('posts'); 

posts.addEventListener('change', (event) => { 
  console.log('A post was created or updated');
  console.log(event.detail.sourcePath, event.detail.isNew); 
});

posts.addEventListener('delete', () => { 
  console.log('A post was deleted');
});

const locales = api.dataset('locales'); 

locales.addEventListener('change', () => { 
  console.log('A locale was created or updated');
});

locales.addEventListener('delete', () => { 
  console.log('A locale was deleted');
});

Update your custom integration after a change#

A common pattern is to re-render your custom integration whenever data changes. For worked examples of re-rendering on change and delete events, debouncing frequent updates, and reading the file that changed, please read our documentation on common patterns for the Visual Editor API.

Clean up listeners#

Remove event listeners when your custom integration is no longer active to avoid memory leaks and unexpected behavior. Always store your listener in a variable so you can pass the same reference to removeEventListener.

const onChange = () => { /* ... */ }; 

api.addEventListener('change', onChange); 

window.addEventListener('beforeunload', () => { 
  api.removeEventListener('change', onChange);
});

If you are building with a framework, clean up listeners in the appropriate lifecycle hook. The following examples use React and Vue, but the approach is the same in any framework: add the listener when the component mounts, and remove it when the component unmounts. Both examples use the withCloudCannonApi helper from initializing the Visual Editor API.

useEffect(() => {
  let api; 
  const onChange = () => { /* ... */ };

  withCloudCannonApi((cloudCannon) => {
    api = cloudCannon;
    api.addEventListener('change', onChange);
  });

  return () => api?.removeEventListener('change', onChange); 
}, []);

let api;
const onChange = () => { /* ... */ };

onMounted(() => {
  withCloudCannonApi((cloudCannon) => {
    api = cloudCannon; 
    api.addEventListener('change', onChange);
  });
});

onUnmounted(() => {
  api?.removeEventListener('change', onChange); 
});