Recent searches

in
Developer ReferenceVisual Editor Api

FileData

On this page

Accessed through a File's data property. Provides structured-data access for a file: its front matter, or the full contents of a data file. Additionally, you can read and write a file's fields, and add, remove, or reorder array items.

Type

Object

Properties

get — Promise<Record<string, any> | any[] | undefined>#

Returns the file's structured data: the front matter of a content file, or the full contents of a data file (JSON, YAML, TOML). The result is an object, or an array when the file's top-level value is a list. Pass slug to read a single field's value instead of the whole object. Resolves to undefined if the file does not exist.

Returns: A promise for the data: an object, an array, or undefined.

Parameters:

  • slug string — The slug of a single field to read, instead of the whole object.

Available on: FileData.

Show examplesHide examples

In this example, we read the whole front matter object, then a single field by slug, and log both.

JavaScript
Copied to clipboard
const data = await api.currentFile().data.get();
const title = await api.currentFile().data.get({ slug: 'title' });
console.log(data, title);
script.js
set — Promise<any>#

Sets a single structured-data field. This marks the file as having unsaved changes; a Team Member must save the Site to persist it. Has no effect if the file does not exist.

Returns: A promise that resolves once the change is applied (with no value).

Parameters:

  • slug string Required — The slug of the field to set.
  • value any Required — The new value for the field.

Available on: FileData.

Show examplesHide examples

In this example, we set the title field to a new value.

JavaScript
Copied to clipboard
await api.currentFile().data.set({ slug: 'title', value: 'My Title' });
script.js
edit — void#

Opens the hosted Data Panel for a single field so a Team Member can edit it. The method returns immediately and does not wait for or report the result of the edit.

Parameters:

  • slug string Required — The slug of the target field.
  • style string | null — Set to "sidebar" to open the field in the Data Editor sidebar instead of a floating Data Panel.
  • position { x: number; y: number; left: number; width: number; top: number; height: number; } — The click coordinates and the bounding rectangle of the element being edited, used to position the panel.

Available on: FileData.

Show examplesHide examples

In this example, we open the Data Panel for the title field.

JavaScript
Copied to clipboard
api.currentFile().data.edit({ slug: 'title' });
script.js
upload — Promise<string | undefined>#

Uploads a file to a specific field (for example, an image or file Input) and returns the uploaded file's path. Setting the field marks the file as having unsaved changes; a Team Member must save the Site to persist it. Resolves to undefined if the file does not exist or the upload produces no path. For a general asset upload that is not tied to a field, use the top-level uploadFile.

Returns: A promise for the uploaded file's path, or undefined.

Parameters:

  • file File Required — The file to upload.
  • slug string Required

Available on: FileData.

Show examplesHide examples

In this example, we upload the file chosen in a file input into the hero_image field and read its path.

JavaScript
Copied to clipboard
const [file] = document.querySelector('input[type="file"]').files;
const path = await api.currentFile().data.upload(file, { slug: 'hero_image' });
script.js
addArrayItem — Promise<void>#

Adds an item to an array field. This marks the file as having unsaved changes; a Team Member must save the Site to persist it. Has no effect if the file does not exist.

Returns: A promise that resolves once the item is added.

Parameters:

  • slug string Required — The slug of the array field.
  • index number | null Required — The position to insert at. Pass null to append to the end.
  • value any — The value to insert. Provide either value for a new item, or sourceIndex to clone an existing one.
  • sourceIndex number — The index of an existing array item to clone, used instead of value.

Available on: FileData.

Show examplesHide examples

In this example, we append a new item to the items array field.

JavaScript
Copied to clipboard
await api.currentFile().data.addArrayItem({
  slug: 'items',
  index: null,
  value: { title: 'New item' },
});
script.js
removeArrayItem — Promise<void>#

Removes an item from an array field by index. This marks the file as having unsaved changes; a Team Member must save the Site to persist it. Has no effect if the file does not exist.

Returns: A promise that resolves once the item is removed.

Parameters:

  • slug string Required — The slug of the array field.
  • index number Required — The index of the item to remove.

Available on: FileData.

Show examplesHide examples

In this example, we remove the item at index 1 from the items array field.

JavaScript
Copied to clipboard
await api.currentFile().data.removeArrayItem({ slug: 'items', index: 1 });
script.js
moveArrayItem — Promise<void>#

Moves an item within an array field, or between two array fields when toSlug differs from fromSlug. This marks the file as having unsaved changes; a Team Member must save the Site to persist it. Has no effect if the file does not exist.

Returns: A promise that resolves once the item is moved.

Parameters:

  • fromSlug string Required — The slug of the array field to move the item from.
  • toSlug string — The slug of the array field to move the item to. Defaults to fromSlug.
  • fromIndex number Required — The current index of the item.
  • toIndex number Required — The target index for the item.

Available on: FileData.

Show examplesHide examples

In this example, we move an item from index 1 to index 2 within the items array field.

JavaScript
Copied to clipboard
await api.currentFile().data.moveArrayItem({
  fromSlug: 'items',
  fromIndex: 1,
  toIndex: 2,
});
script.js
Open in a new tab