Access and list files, Collections, and Datasets with the Visual Editor API

CloudCannon's Visual Editor API exposes files, Collections, and Datasets from your Site code. This article covers how to access and list each one, and how to apply type guards before you call type-specific methods on mixed values.

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

Files#

Calling *.files() on the API Object returns an array of every file across your Site. To access an individual file, use *.currentFile(), which returns the file currently open in the Visual Editor, or *.file(path), which returns a specific file by its source path regardless of what is currently open.

To list all files:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call await *.files() for an array of every file in your Site.

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

for (const file of allFiles) { 
  const data = await file.data.get();
  console.log(file.path, data?.title);
}

To access a file:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call *.currentFile() for the file open in the preview, or *.file('/path/example.md') with a path relative to your Site root.

const current = api.currentFile(); 
const specific = api.file('/content/pages/about.md'); 

To handle a page with no associated file, wrap *.currentFile() in a try/catch and check the result before using it:

let file;

try {
  file = api.currentFile(); 
} catch (error) {
  console.warn('No file is associated with this page.'); 
}

if (file) { 
  const data = await file.data.get();
  console.log(data);
}

Collections#

A Collection is a folder of files with a similar format, defined under collections_config in your CloudCannon Configuration File. Calling *.collections() on the API Object returns an array of every configured Collection on the Site, while *.collection() accesses one.

To list all Collections:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call await *.collections() for an array of every configured Collection.

const allCollections = await api.collections(); 

for (const collection of allCollections) { 
  console.log(collection.collectionKey);
}

To access a Collection and list its files:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call *.collection('example-key'), where example-key is a Collection key under collections_config in your CloudCannon Configuration File.
4. Await *.items() on the returned object for an array of file objects.

const posts = api.collection('posts'); 
const files = await posts.items(); 

for (const file of files) { 
  const data = await file.data.get();
  console.log(file.path, data?.title);
}

Datasets#

A Dataset is a structured data file or folder defined under data_config in your CloudCannon Configuration File, such as navigation links, locale strings, or site settings. Calling *.datasets() on the API Object returns an array of every configured Dataset on the Site, while *.dataset() accesses one.

To list all Datasets:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call await *.datasets() for an array of every configured Dataset.

const allDatasets = await api.datasets(); 

for (const dataset of allDatasets) { 
  console.log(dataset.datasetKey);
}

To access a Dataset and list its files:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Call *.dataset('example-key'), where example-key is a Dataset key under data_config in your CloudCannon Configuration File.
4. Await *.items() on the returned object. If the Dataset is a folder path, it returns an array; if it is a single file path, it returns one file object.

const locales = api.dataset('locales'); 
const result = await locales.items(); 

if (Array.isArray(result)) { 
  for (const file of result) {
    const data = await file.data.get();
    console.log(file.path, data?.title);
  }
} else {
  const data = await result.data.get(); 
  console.log(result.path, data?.title);
}

Because *.items(), *.files(), *.collections(), and *.datasets() return arrays, you can filter, sort, or transform the results with standard JavaScript. For worked examples, including filtering a Collection by a field, please read our documentation on common patterns for the Visual Editor API.

Type guards#

The API Object provides the *.isAPIFile(), *.isAPICollection(), and *.isAPIDataset() type guard functions to check whether an object is a file, Collection, or Dataset. These are useful when working with mixed results or when you need to narrow the type of an object before calling methods on it.

To branch on a value that might be a file, Collection, or Dataset:

1. Open your website files in your local development environment.
2. Open the JavaScript file where your Visual Editor API integration runs.
3. Pass the value to *.isAPIFile(), *.isAPICollection(), or *.isAPIDataset().

When a guard returns true, call only the methods that exist on that type (for example, *.data.get() on a file object, or await *.items() on a Collection or Dataset handle), so TypeScript and the runtime agree on the object shape.

if (api.isAPIFile(obj)) { 
  const data = await obj.data.get();
}

if (api.isAPICollection(obj)) { 
  const items = await obj.items();
}

if (api.isAPIDataset(obj)) { 
  const items = await obj.items();
}