Represents a single file in your Site. Returned by the
currentFile(), file(), and files() methods, and by a Collection's or
Dataset's items() method. Additionally, you can read and write a File's raw source,
body content, and structured data, read its metadata, and lock it while you
edit.
Type
Object
Properties
Holds the file's source path, relative to the Site root.
Available on: File.
Show examplesHide examples
In this example, we read a file's source path and log it.
const path = api.currentFile().path;
console.log(path);Provides structured-data access for the file (front matter, or a data file's contents). Use the methods on the FileData object to read and write the data.
Available on: File.
Show examplesHide examples
In this example, we get the FileData object for the file open in the editor.
const data = api.currentFile().data;Provides body-content access for the file (everything after the front matter). Use the methods on the FileContent object to read and write the body.
Available on: File.
Show examplesHide examples
In this example, we get the FileContent object for the file open in the editor.
const content = api.currentFile().content;Returns the file's entire raw source (front matter and body) as a string.
Use content.get() for the body alone, or data.get() for the parsed front
matter. Resolves to undefined if the file does not exist.
Returns: A promise for the raw source string.
Available on: File.
Show examplesHide examples
In this example, we read the raw source of the file open in the editor and log it.
const raw = await api.currentFile().get();
console.log(raw);Replaces the file's entire raw source with the given string. Use this for
files that aren't edited through structured data, such as a
robots.txt. 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.
Parameters:
valuestringRequired — The new raw source, as a string.
Available on: File.
Show examplesHide examples
In this example, we read a file's raw source, replace some text, and write it back.
const file = api.file('/public/robots.txt');
const raw = await file.get();
await file.set(raw.replace('old text', 'new text'));Returns the file's metadata: { file_size, created_at, last_modified, data },
where data is the file's resolved output data (its front matter merged with
the data CloudCannon's build produces for it), not the same as the File's
data object. Metadata is read-only and cannot be written through the API.
Resolves to undefined if the file does not exist.
Returns: A promise for the file's metadata.
Available on: File.
Show examplesHide examples
In this example, we read the metadata of the file open in the editor and log it.
const meta = await api.currentFile().metadata();
console.log(meta);Claims an editing lock on the file so other Team Members cannot change it
while your integration writes to it. Resolves to { readOnly }. When
readOnly is true, another Team Member already holds the lock for that
file and your integration should not write. Resolves to undefined if the
file does not exist. Release the lock with releaseLock() when you are done.
Returns: A promise for the lock status, { readOnly: boolean }.
Available on: File.
Show examplesHide examples
In this example, we claim the lock on the file we're editing, write a field only if no one else holds it, then release it.
const file = api.currentFile();
const { readOnly } = await file.claimLock();
if (!readOnly) {
await file.data.set({ slug: 'status', value: 'in-progress' });
await file.releaseLock();
}Releases a lock claimed with claimLock(), letting other Team Members edit
the file again. Resolves to undefined if the file does not exist.
Returns: A promise for the lock status, { readOnly: boolean }.
Available on: File.
Show examplesHide examples
In this example, we release a lock on the file we're editing.
await api.currentFile().releaseLock();Listens for change and delete events on the file. change fires when
the file is created or updated, and delete when it 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 messages when the file changes or is deleted.
const file = api.currentFile();
file.addEventListener('change', () => console.log('Changed'));
file.addEventListener('delete', () => console.log('Deleted'));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 changes to the file on teardown.
const file = api.currentFile();
const onChange = () => console.log('Changed');
file.addEventListener('change', onChange);
file.removeEventListener('change', onChange);Returns the resolved Input configuration for a field, or undefined when the
field has no configuration (or the file does not exist).
Returns: A promise for the field's Input configuration.
Parameters:
slugstringRequired — The slug of the field whose Input configuration to resolve.
Available on: File.
Show examplesHide examples
In this example, we read the resolved Input configuration for the hero_image field and log it.
const config = await api.currentFile().getInputConfig({ slug: 'hero_image' });
console.log(config);