Methods exposed by the v1 Visual Editor API, available via window.CloudCannonAPI.useVersion('v1', true).
Type
Object
Properties
Returns the files CloudCannon has prefetched for the current editing
session, as a map of source path to Blob.
Returns: A promise for the prefetched files.
Available on: API Object.
Show examplesHide examples
In this example, we read the files CloudCannon prefetched for this session.
const files = await api.prefetchedFiles();Shows or hides the Visual Editor's loading overlay. Pass a message to show
the overlay while your integration performs async setup, or undefined to
clear it.
Returns: A promise that resolves once the loading state is applied.
Parameters:
loadingDatastring | undefinedRequired — The message to show, orundefinedto hide the overlay.
Available on: API Object.
Show examplesHide examples
In this example, we show the loading overlay during async work, then clear it.
await api.setLoading('Loading data…');
// …async work…
await api.setLoading(undefined);Uploads a file through CloudCannon's asset handling and returns its path.
Pass undefined as the second argument for default behavior, or an Input
configuration to control where the file is uploaded and which asset sources
or DAMs are offered. To upload into a specific field, use file.data.upload
instead. Resolves to undefined if the upload produces no path.
Returns: A promise for the uploaded file's path, or undefined.
Parameters:
fileFileRequired — The file to upload.inputConfigRichTextInput | UrlInput | FileInput | undefinedRequired — Optional Input configuration, orundefinedfor defaults.
Available on: API Object.
Show examplesHide examples
In this example, we upload an image with default asset handling.
const path = await api.uploadFile(new File([blob], 'image.png'), undefined);Returns the file currently open in the Visual Editor. Not every page has an associated file, and this throws when the open page has none.
Returns: The file open in the preview.
Throws: 'No current file path' when no file is open.
Available on: API Object.
Show examplesHide examples
In this example, we read the open file, wrapping the call in a try/catch
to handle a page with no associated file.
try {
const file = api.currentFile();
} catch (err) {
// The open page has no associated file.
}Returns the file at a source path, relative to the Site root, regardless of
which page is open. This never throws; calling a method on a file whose path
doesn't exist resolves to undefined.
Returns: The file at that path.
Parameters:
pathstringRequired — The file's source path (for example,/content/pages/about.md).
Available on: API Object.
Show examplesHide examples
In this example, we reference a file by its source path.
const about = api.file('/content/pages/about.md');Returns a Collection object for the given key, as configured under
collections_config in your CloudCannon Configuration File. The object
provides methods to list the Collection's items and listen for changes,
not the items themselves.
Returns: A Collection object with methods to list items and subscribe to changes.
Parameters:
keystringRequired — The Collection key.
Available on: API Object.
Show examplesHide examples
In this example, we reference the posts Collection by key.
const posts = api.collection('posts');Returns the Dataset with the given key, as configured under data_config in
your CloudCannon Configuration File.
Returns: The Dataset.
Parameters:
keystringRequired — The Dataset key.
Available on: API Object.
Show examplesHide examples
In this example, we reference the locales Dataset by key.
const locales = api.dataset('locales');Returns every file in the Site as an array of File objects.
Returns: A promise for all files.
Available on: API Object.
Show examplesHide examples
In this example, we list every file in the Site and log each path.
const files = await api.files();
for (const file of files) console.log(file.path);Returns every configured Collection in the Site as an array of Collection objects.
Returns: A promise for all Collections.
Available on: API Object.
Show examplesHide examples
In this example, we list every Collection in the Site and log each key.
const collections = await api.collections();
for (const collection of collections) console.log(collection.collectionKey);Returns every configured Dataset in the Site as an array of Dataset objects.
Returns: A promise for all Datasets.
Available on: API Object.
Show examplesHide examples
In this example, we list every Dataset in the Site and log each key.
const datasets = await api.datasets();
for (const dataset of datasets) console.log(dataset.datasetKey);Listens for change and delete events across the entire Site. change
fires when any file is created or updated, and delete when any file is
removed. Remove the listener with removeEventListener when your integration
is torn down.
Available on: API Object, Collection, Dataset, File.
Show examplesHide examples
In this example, we log the path of any file that changes anywhere in the Site.
api.addEventListener('change', (event) => {
console.log('Changed:', event.detail.sourcePath);
});Removes a change or delete listener previously added with addEventListener.
Available on: API Object, Collection, Dataset, File.
Show examplesHide examples
In this example, we stop listening for Site-wide changes on teardown.
const onChange = (event) => console.log('Changed:', event.detail.sourcePath);
api.addEventListener('change', onChange);
api.removeEventListener('change', onChange);Type guard that returns true when obj is a File object.
Parameters:
objunknownRequired — The value to check.
Available on: API Object.
Show examplesHide examples
In this example, we narrow an unknown value to a File before using it.
if (api.isAPIFile(obj)) {
const data = await obj.data.get();
}Type guard that returns true when obj is a Collection object.
Parameters:
objunknownRequired — The value to check.
Available on: API Object.
Show examplesHide examples
In this example, we narrow an unknown value to a Collection before using it.
if (api.isAPICollection(obj)) {
const items = await obj.items();
}Type guard that returns true when obj is a Dataset object.
Parameters:
objunknownRequired — The value to check.
Available on: API Object.
Show examplesHide examples
In this example, we narrow an unknown value to a Dataset before using it.
if (api.isAPIDataset(obj)) {
const items = await obj.items();
}Finds the Structure value whose conditions match a given data object, the same way CloudCannon picks a Structure entry for a value.
Returns: The matching Structure value, or undefined if none match.
Parameters:
structureStructureRequired — The Structure to search.valueanyRequired — The data object to match against the Structure's values.
Available on: API Object.
Show examplesHide examples
In this example, we find the Structure value that matches a data object.
const match = api.findStructure(structure, { type: 'hero' });Returns the Input type CloudCannon would use for a field (such as text,
image, or select), based on its key, value, and any Input configuration.
Returns: The resolved Input type.
Parameters:
keystring | undefinedRequired — The field key.valueunknown— The field value.inputConfigInput— Optional Input configuration for the field.
Available on: API Object.
Show examplesHide examples
In this example, we resolve the Input type CloudCannon would use for a field.
const type = api.getInputType('hero_image', '/img.png');Makes a supported HTML element directly editable in the Visual Editor page
preview. Clicking the element opens a rich text toolbar and edits its content
in place. Returns a region object whose setContent updates the content
programmatically.
Returns: A promise for the editable region.
Throws: 'Parent window not yet initialized' when called before the editor is ready.
Parameters:
elementHTMLElementRequired — The element to make editable.onChange(content?: string | null) => voidRequired — Called with the updated content whenever it changes.elementTypestring— The family of HTML element being edited:text,block,span,image, orlink. Inferred from the tag name if omitted (for example,h2astext,divasblock).editableTypestring— The editing mode. Use the same value aselementType, orcontentwhen editing body content.inputConfigRichTextInput— Controls which rich text toolbar options are available.extensionstring— The file extension used when saving the edited fragment (for example,.htmlor.md). Match it to the format of the underlying file.
Available on: API Object.
Show examplesHide examples
In this example, we make a heading element editable in the page preview.
const region = await api.createTextEditableRegion(
document.querySelector('#hero-heading'),
(content) => console.log('Updated:', content),
);Opens a custom Data Panel in the Visual Editor and resolves with the
panel's id. When options.id is omitted, CloudCannon generates a
seven-character base-36 id. Pass the returned id to
destroyCustomDataPanel to close the panel.
Returns: A promise for the panel's id.
Parameters:
idstring— A stable identifier for the panel. Pass it todestroyCustomDataPanelto close the panel. When omitted, CloudCannon generates a seven-character base-36 id (digits0-9and lowercasea-z, e.g.k4j92xq).titlestringRequired — The heading shown at the top of the Data Panel.onChange(data?: Record<string, unknown> | unknown[]) => voidRequired — Called whenever a Team Member changes a value in the panel. Receives the full updated data object, not a diff.dataRecord<string, unknown> | unknown[]— Initial values for the panel, keyed by Input name. Each key becomes an editable field configured byconfig.configCascade— Input configuration for the fields indata, using the same_inputsshape as a CloudCannon Configuration File.positionDOMRect— ADOMRect(for example fromgetBoundingClientRect()) used to anchor the panel next to the control that opened it. When omitted, CloudCannon positions the panel.allowFullDataCascadeboolean— Whentrue, Inputs resolve against the previewed file and the Site configuration the same way hosted Data Panels do (for example, for Structure matching). Whenfalse(the default), only thedataandconfigpassed here are used.
Available on: API Object.
Show examplesHide examples
In this example, we open a custom Data Panel and log its data whenever it changes.
const panelId = await api.createCustomDataPanel({
title: 'Image SEO',
onChange: (data) => console.log(data),
});Closes the custom Data Panel with the given id.
Returns: A promise that resolves once the panel is closed.
Parameters:
idstringRequired — The id returned bycreateCustomDataPanel.
Available on: API Object.
Show examplesHide examples
In this example, we close a custom Data Panel by its id.
await api.destroyCustomDataPanel(panelId);Returns a URL that works inside the Visual Editor for a file that may not yet be committed to the Site, such as an image uploaded in the current editing session. Use this instead of the source path when displaying media.
Returns: A promise for a preview URL.
Throws: 'Parent window not yet initialized' when called before the editor is ready.
Parameters:
originalUrlstringRequired — The source path to rewrite.inputConfigInput— Optional Input configuration.
Available on: API Object.
Show examplesHide examples
In this example, we read a preview URL for an image that may not be committed yet.
const url = await api.getPreviewUrl('/images/hero.jpg');