$files
Updated on Aug 25, 2025 24 minutes to readThe Files Plugin provides a set of methods to manage, upload, download, preview, and manipulate files in the application.
Methods
| Method | Description |
|---|---|
| chooseFile | Opens the device file selection dialog. |
| download | Downloads a file by ID. |
| downloadArchive | Downloads a server-generated ZIP archive by file IDs. |
| downloadBase64 | Downloads a file and returns its Base64 string. |
| getDownloadUrl | Returns the URL to download a file. |
| getInfo | Returns detailed information about a file. |
| getPublicUrl | Returns the public URL of a file. |
| getThumbnailUrl | Returns the URL of a file thumbnail. |
| manipulateFile | Resizes, converts, or compresses an image or video. |
| makePrivate | Sets a file to private. |
| makePublic | Sets a file to public. |
| preview | Previews a file or a list of files. |
| previewOrDownload | Previews a file if supported or downloads it otherwise. |
| readZip | Reads a ZIP directory and extracts files by path. |
| unzip | Extracts files from a ZIP archive. |
| upload | Uploads a file from local selection or mobile device. |
| uploadBase64 | Uploads a file from a Base64 string. |
| uploadFile | Uploads an existing File without a selection dialog. |
| zip | Creates and downloads a ZIP archive. |
Methods Details
chooseFile()
• Type
(accept?: string) => Promise<File>• Details
Expects an optional accept value in the HTML file input format. For example, .zip,application/zip restricts selection to ZIP archives.
If the user cancels the dialog, the Promise is rejected with an error whose code is FILE_SELECTION_CANCELLED.
Opens the device file selection dialog and returns a Promise that resolves with the selected File.
download()
• Type
(id: string, params?: DownloadFileParams) => void• Details
Expects a file ID
and optional DownloadFileParams (default: { inline: true } if the MIME type is application/pdf and the environment is not a mobile application; { inline: false } in all other cases).
Downloads the file to the client or device.
downloadArchive()
• Type
(
entries: Array<string | ArchiveFileEntry>,
archiveName?: string
) => Promise<void>• Details
Expects a non-empty array of file IDs or ArchiveFileEntry objects, and an optional archive name (default: files.zip).
If an entry path is omitted, the original file name is used. The .zip extension is added to the archive name when omitted. Archive paths must be relative and must not contain empty, . or .. segments. Absolute paths and unsafe file-name characters are rejected by the server.
Returns a Promise that resolves after the server-generated ZIP download is started. The server streams the archive directly to the device without downloading the source file contents into browser memory first.
downloadBase64()
• Type
(id: string) => Promise<string>• Details
Expects a file ID.
Returns a Promise that resolves with the Base64 string representation of the file.
getDownloadUrl()
• Type
(id: string, schema?: boolean, params?: BaseFileParams) => string• Details
Expects a file ID,
an optional schema flag (default: false) that specifies whether the returned URL should be absolute or relative,
and optional BaseFileParams (default: null).
Returns the URL to download the file.
getInfo()
• Type
(id: string) => Promise<FileInfo>
(ids: string[]) => Promise<FileInfo[]>• Details
Expects a file ID or an array of file IDs.
For a single ID, returns a Promise that resolves with a FileInfo object. For an array of IDs, returns a Promise that resolves with an array of FileInfo objects.
The response is cacheable by the browser. Since every file has a unique ID and its type does not change, repeated calls with the same ID or the same array of IDs can be served from the browser cache.
getPublicUrl()
• Type
(id: string, schema?: boolean) => Promise<string | null>• Details
Expects a file ID
and optional schema flag (default: false) that specifies whether the returned URL should be absolute or relative,
Returns a Promise that resolves with the public URL of the file if available, or null.
getThumbnailUrl()
• Type
(
id: string,
size?: number,
schema?: boolean,
params?: ThumbnailFileParams
) => string• Details
Expects a file ID,
an optional size (default: 50),
an optional schema flag (default: false) that specifies whether the returned URL should be absolute or relative,
and optional ThumbnailFileParams.
Returns the URL of the file thumbnail.
makePrivate()
• Type
(id: string) => Promise<void>• Details
Expects a file ID.
Sets the file as private and returns a Promise that resolves when complete.
makePublic()
• Type
(id: string, params?: PublicFileParams) => Promise<void>• Details
Expects a file ID and optional PublicFileParams.
Sets the file as public and returns a Promise that resolves when complete.
preview()
• Type
(
id: string | string[],
params?: PreviewFileParams
) => Promise<boolean>• Details
Expects a file ID or array of file IDs and optional PreviewFileParams (default: null).
Previews the file if supported. Returns a Promise that resolves with true if preview is shown successfully, false otherwise.
previewOrDownload()
• Type
(
id: string,
params?: PreviewFileParams | DownloadFileParams
) => Promise<boolean>• Details
Expects a file ID and optional PreviewFileParams or DownloadFileParams (default: null).
Previews the file if supported or downloads it otherwise. Returns a Promise resolving to true if action is successful, false otherwise.
upload()
• Type
(
ownerScriptAlias: E8ScriptAlias,
attrScriptAlias: E8ScriptAlias,
progressCallback?: Function
) => Promise<FileInfo>• Details
Expects E8ScriptAlias for owner and attribute, and optional progress callback.
Uploads a selected file and returns a Promise resolving with a FileInfo object.
uploadBase64()
• Type
// Overload 1: single object parameter
(uploadBase64DataParams: UploadBase64DataParams) => Promise<FileInfo>;
// Overload 2: separate parameters
(
ownerScriptAlias: E8ScriptAlias,
attrScriptAlias: E8ScriptAlias,
data: UploadBase64Data,
progressCallback?: Function
) => Promise<FileInfo>;• Details
Overload 1: Expects a structured object (UploadBase64DataParams).
Overload 2: Expects individual parameters: ownerScriptAlias (E8ScriptAlias), attrScriptAlias (E8ScriptAlias), data (UploadBase64Data) with basename and base64str, and optional progressCallback function.
Returns a Promise that resolves with the uploaded FileInfo object.
manipulateFile()
• Type
(
file: File,
options?: FileManipulationOptions | null
) => Promise<File>• Details
Expects a File and optional FileManipulationOptions. The options contain ImageManipulationOptions or VideoManipulationOptions.
Returns a Promise that resolves with the resized, converted, or compressed File. The image aspect ratio is preserved. Unsupported file types and files that do not require manipulation are returned unchanged.
readZip()
• Type
(
archiveFile: File | Blob | ArrayBuffer | Uint8Array,
options?: ReadZipOptions
) => Promise<ZipArchive>• Details
Expects ZIP data as a File, Blob, ArrayBuffer, or Uint8Array, and optional ReadZipOptions. A File returned by chooseFile() can be passed directly.
Returns a Promise that resolves with a ZipArchive object. It reads the ZIP directory without extracting all file contents and provides metadata as ZipArchiveEntryInfo objects together with indexed access to individual entries:
entriescontains metadata for all files and explicit directory entries;has(path)checks whether an exact path exists;list(directoryPath)returns all descendants of a directory, or all entries when the path is omitted;getFile(path)extracts only the requested file and returnsnullwhen it does not exist or represents a directory;close()releases resources associated with the archive.
Paths are relative to the ZIP root. Call close() in a finally block when the archive is no longer needed.
The default limits are 512 MiB per entry, 10 GiB total uncompressed size, and 100,000 files. They can be changed with ReadZipOptions.
unzip()
• Type
(
archiveFile: File | Blob | ArrayBuffer | Uint8Array,
options?: UnzipOptions
) => Promise<UnzippedFile[]>• Details
Expects ZIP data as a File, Blob, ArrayBuffer, or Uint8Array, and optional UnzipOptions. A File returned by chooseFile() can be passed directly. The callbacks receive UnzippedFile, UnzipFileInfo, and UnzipProgress values.
Without onFile, all extracted files are returned and retained in memory. The default maximum collected size is 256 MiB.
When onFile is provided, files are extracted and processed sequentially and are not retained by default. Set collectFiles: true to also include them in the returned array.
Returns a Promise that resolves with an array of UnzippedFile objects. Each file has a relativePath property containing its full path inside the archive.
uploadFile()
• Type
(
ownerScriptAlias: E8ScriptAlias,
attrScriptAlias: E8ScriptAlias,
file: File,
progressCallback?: Function
) => Promise<FileInfo>• Details
Expects the owner and attribute script aliases, the File to upload, and an optional progress callback.
Uploads the file without opening a file selection dialog and returns a Promise resolving with a FileInfo object.
zip()
• Type
(
entries: Array<File | ZipEntry>,
archiveName?: string
) => Promise<File>• Details
Expects an array of File values or ZipEntry objects, and an optional archive name (default: archive.zip).
A plain File uses its relativePath, webkitRelativePath, or file name as its path inside the archive. A ZipEntry can provide an explicit relative path. Duplicate, absolute, and unsafe paths are rejected. The .zip extension is added to the archive name when omitted.
Creates the ZIP archive in the browser, starts one download of the completed archive, and returns a Promise that resolves with the created ZIP as a File.
Use downloadArchive() instead when all source files are already stored on the server and identified by ID. This allows the server to build and stream the archive without first downloading every source file into browser memory.