Initialize the Visual Editor API

CloudCannon's Visual Editor API allows you to read and write content, listen for changes, and build custom integrations in the Visual Editor. This article covers how to set up and initialize the Visual Editor API in your website's JavaScript.

This article assumes you know how to detect the Visual Editor in your site's JavaScript. For a complete list of API objects and methods, please read our reference documentation on the Visual Editor API.

Install the package#

The @cloudcannon/visual-editor-api package provides TypeScript declarations for the Visual Editor API. This package contains type definitions only, and no runtime code. The actual API is provided by CloudCannon when your website loads in the Visual Editor.

To install the package as a dev dependency:

1. Open your local terminal and navigate to the root folder of your website project.
2. Run the following command in your terminal:

npm install --save-dev @cloudcannon/visual-editor-api

npm will install the type definitions for the Visual Editor API.

If your project uses TypeScript, please read our documentation on using TypeScript with the Visual Editor API for instructions on setting up type declarations and IDE autocomplete.

Initialize the API#

The Visual Editor API is available through window.CloudCannonAPI whenever you open a file in the Visual Editor. To use the API, you need to:

• Check if the Visual Editor API has loaded in the Visual Editor (your website's scripts may run before the API finishes loading),
• Get the v1 API Object,
• Use the returned object to call API methods.

You can detect whether the API has already loaded by the time your script runs by checking whether window.CloudCannonAPI already exists. You can also listen for the cloudcannon:load event on document, if your script runs before the API finishes loading.

To initialize the Visual Editor API in your JavaScript:

1. Open your website files in your local development environment.
2. Create a Promise that resolves with the v1 API Object once the API is ready.
3. Await the Promise in an async function and add your integration code.

const apiPromise = new Promise((resolve) => { 
  if (window.CloudCannonAPI) {
    const api = window.CloudCannonAPI.useVersion('v1', true);
    resolve(api);
  } else {
    document.addEventListener( 
      'cloudcannon:load',
      () => {
        const api = window.CloudCannonAPI.useVersion('v1', true);
        resolve(api);
      },
      { once: true }
    );
  }
});

(async () => { 
  const api = await apiPromise;
  // Custom integration code here
})();

const api = window.CloudCannonAPI.useVersion('v1', true);
// api is only accessible through the returned object, not through window.CloudCannon

This is one approach. You can adapt it to suit your project, for example by wrapping the await in a framework lifecycle hook. Alternatively, you can use a callback-based helper:

function withCloudCannonApi(callback) { 
  const setup = (router) => {
    const api = router?.useVersion('v1', true);
    if (api) callback(api);
  };

  if (window.CloudCannonAPI) {
    setup(window.CloudCannonAPI);
    return;
  }

  document.addEventListener(
    'cloudcannon:load',
    () => setup(window.CloudCannonAPI),
    { once: true }
  );
}

withCloudCannonApi(async (api) => { 
  // Custom integration code here
});

Once you have the API initialized, you can read and write data, listen for changes, list files, Collections, and Datasets, create a custom data panel, create custom inline editing, and manage loading, uploads, and previews.