Read and write data with the Visual Editor API

CloudCannon's Visual Editor API exposes each website file as an object you open from your Site code. After you have that file reference, you can read and write structured data in front matter or data files, work with body content, read or replace raw source, read file metadata, add or remove array items or change their order, open the hosted Data Panel for a single field, and claim a file lock while you coordinate updates with other Team Members editing in the Visual Editor.

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.

Read and write file data#

You can read and write to your website files with the Visual Editor API using the following functions:

• Use *.data.get() and *.data.set() for structured data: the front matter of a content file, or the full contents of a data file (such as JSON or YAML).
• Use *.content.get() and *.content.set() for file body content.
• Use *.get() and *.set() for raw source.
• Use *.metadata() for file metadata (you cannot write to file metadata).

Structured data

Calling *.data.get() returns the structured data in the accessed file: every field in the front matter of a content file, or the full contents of a data file (such as JSON or YAML). The Visual Editor API returns a JavaScript object, or a JavaScript array if the file's top-level value is a list.

const api = window.CloudCannonAPI.useVersion('v1', true);
const file = api.currentFile(); 
const frontmatter = await file.data.get(); 
console.log(frontmatter); 
console.log(frontmatter.title); 

You can also read one field at a time by passing a slug option to *.data.get(). When you supply { slug: 'author' }, CloudCannon returns only that field's value instead of the entire object.

const file = api.currentFile();
const author = await file.data.get({ slug: 'author' }); 
console.log(author);

Calling *.data.set() allows you to write to a structured data field in an accessed file by passing the field's slug and the new value. This updates the Visual Editor data model and marks the file as having unsaved changes. The change will be visible in any open Editing Interfaces (not only the Visual Editor).

const file = api.currentFile(); 
await file.data.set({ 
  slug: 'title', 
  value: 'Updated title' 
});

*.data.set() updates one field per call. To update several fields, call it once for each field.

Body content

Body content is the part of a file that comes after the front matter (for example, the Markdown body of a blog post).

Calling *.content.get() allows you to read the body content of an accessed file as a string, or undefined if the file does not exist.

const file = api.currentFile(); 
const content = await file.content.get(); 
console.log(content); 

Calling *.content.set() allows you to replace the body content of an accessed file by passing a string. This updates the Visual Editor data model and marks the file as having unsaved changes. The change will be visible in any open Editing Interfaces.

const file = api.currentFile(); 
const content = await file.content.get(); 
await file.content.set(`${content}\n\nAppended paragraph.`); 

Raw source

Calling *.get() allows you to read the entire raw source of an accessed file as a string, including both front matter and body content. Use this when you need access to the complete file rather than structured data or body content separately.

const file = api.currentFile(); 
const raw = await file.get(); 
console.log(raw); 

Calling *.set() allows you to replace the entire raw source of an accessed file by passing a string. Use this for files that are not structured data, or that are not normally editable through CloudCannon. This updates the Visual Editor data model and marks the file as having unsaved changes. The change will be visible in any open Editing Interfaces.

const file = api.file('/public/robots.txt'); 
const raw = await file.get(); 
await file.set(raw.replace('old text', 'new text')); 

File metadata

Calling *.metadata() allows you to read metadata about an accessed file, such as its file size and when it was created or last modified. File metadata is read-only. You cannot write to it using the Visual Editor API.

const file = api.file('/content/pages/about.md'); 
const meta = await file.metadata(); 
console.log(meta); 

Open the Visual Editor Data Panel#

You can use Data Panels in CloudCannon's Visual Editor to edit the value of structured data fields in your files.

By calling *.data.edit() and passing a slug option, you can open a Data Panel for a specific field. This is useful when you want to use CloudCannon's built-in interface for your custom integration.

Optionally, pass a position object to anchor the Data Panel to the HTML element that triggered the action (for example, the element the Team Member clicked).

const file = api.currentFile(); 
const element = document.querySelector('#hero-image'); 

element.addEventListener('click', (event) => { 
  const rect = element.getBoundingClientRect(); 
  file.data.edit({ 
    slug: 'hero_image', 
    position: { 
      x: event.clientX,
      y: event.clientY,
      left: rect.left,
      width: rect.width,
      top: rect.top,
      height: rect.height
    }
  });
});

Edit Array Inputs#

You can use the Visual Editor API to add, remove, and reorder items in an Array Input, either in the front matter of a content file or in a data file.

Add an item

Calling *.data.addArrayItem() allows you to add an item to an array field in an accessed file.

const file = api.currentFile(); 
await file.data.addArrayItem({ 
  slug: 'items', 
  index: null, 
  value: { title: 'New item', description: '' } 
});

Remove an item

Calling *.data.removeArrayItem() allows you to remove an item from an array field in an accessed file.

const file = api.currentFile(); 
await file.data.removeArrayItem({ 
  slug: 'items', 
  index: 2 
});

Move an item

Calling *.data.moveArrayItem() allows you to reorder items within an array field, or move items between different array fields, in an accessed file.

const file = api.currentFile(); 
await file.data.moveArrayItem({ 
  fromSlug: 'items', 
  fromIndex: 0, 
  toIndex: 3 
});

Lock editing on a file#

Claiming a lock on a file gives your integration the editing lock for that file. Only one lock can be held at a time, so other Team Members working in the Visual Editor see the file as read-only while your integration holds it. Use *.file() to access the file you want to lock, call claimLock() before making changes, and releaseLock() when you are done.

const file = api.file('/_data/settings.yml'); 
const lock = await file.claimLock(); 

if (lock && !lock.readOnly) { 
  try {
    await file.data.set({ slug: 'status', value: 'in-progress' });
  } finally {
    await file.releaseLock(); 
  }
}

A lock is cooperative, not absolute. A Team Member editing in the Visual Editor can take the lock from your integration at any time: when they open a file that is already being edited, CloudCannon shows them a banner with a Switch to editing button. Clicking it hands them the lock, moves your integration to read-only, and keeps any unsaved changes. Because a held lock is not a guarantee of exclusive access, call claimLock() again and check readOnly before resuming writes to confirm your integration still holds the lock. For how this looks to a Team Member in the Visual Editor, please read our documentation on Editing sessions and collaboration.

Read Input configuration#

Calling *.getInputConfig() allows you to read the resolved Input configuration for a field in an accessed file. Pass a slug option to specify the field.

const file = api.currentFile(); 
const inputConfig = await file.getInputConfig({ slug: 'hero_image' }); 
console.log(inputConfig?.type);