diff --git a/content/scripts/api-reference/input.mdx b/content/scripts/api-reference/input.mdx index 91f281b9..26bffad6 100644 --- a/content/scripts/api-reference/input.mdx +++ b/content/scripts/api-reference/input.mdx @@ -13,7 +13,8 @@ Input methods are asynchronous and pause script execution until the user provide - Collect text input from users - Present users with choices using buttons or dropdown menus - Allow users to select tables, views, fields, or records -- Collect file uploads for data processing +- Upload and parse files for data processing (`fileAsync`) +- Upload files for attachments and storage (`uploadFileAsync`) All input methods return a Promise that resolves to the value provided by the user, so they must be used with `await` to get the result. @@ -195,6 +196,82 @@ if (result && result.parsedContents) { **Output:** ![File Input Example](/img/v2/scripts/input-file-1.png) +### input.uploadFileAsync() + +Prompts the user to upload one or more files and returns raw file objects. This method is ideal for storing files in the database. + +**Parameters:** +- `label` (`string`): The prompt text to display to the user +- `options` (`object`, optional): Additional options for file upload: + - `allowedFileTypes` (`Array`): File extensions, MIME types, or wildcard patterns to accept (e.g., `'.pdf'`, `'image/*'`, `'application/json'`) + +**Returns:** `Promise` - A promise that resolves to an array of file objects + +**NocoDbFile Interface:** +```typescript +interface NocoDbFile { + url?: string; // File URL + title: string; // File name + mimetype: string; // MIME type + size: number; // File size in bytes + signedUrl?: string; // Signed URL for secure access (preferred) + thumbnails?: { // Available for images + tiny: { signedPath: string; signedUrl: string; }; + small: { signedPath: string; signedUrl: string; }; + card_cover: { signedPath: string; signedUrl: string; }; + }; +} +``` + +**Example - Basic file upload:** +```javascript +// Prompt user to upload any file +const files = await input.uploadFileAsync("Please upload your document"); + +console.log(`Uploaded ${files.length} file(s)`); +files.forEach(file => { + console.log(`File: ${file.title}, Size: ${file.size} bytes`); +}); +``` + +**Example - Upload images only:** +```javascript +// Restrict to image files only +const images = await input.uploadFileAsync("Upload product images", { + allowedFileTypes: ['image/*'] +}); + +// Process uploaded images +for (const image of images) { + console.log(`Image: ${image.title}`); + console.log(`MIME Type: ${image.mimetype}`); + console.log(`URL: ${image.signedUrl || image.url}`); +} +``` + +**Example - Upload spreadsheets:** +```javascript +// Accept only Excel and CSV files +const spreadsheets = await input.uploadFileAsync("Upload sales data", { + allowedFileTypes: ['.xlsx', '.csv', 'application/vnd.ms-excel'] +}); + +console.log(`Received ${spreadsheets.length} spreadsheet(s)`); +``` + +**Example - Store uploaded files in database:** +```javascript +const files = await input.uploadFileAsync("Upload product images"); + +await table.createRecordAsync({ + 'AttachmentField': files, +}); +``` + +**Output:** +![File Input Example](/img/v2/scripts/input-uploadFileAsync.png) + + ### input.tableAsync() Prompts the user to select a table from the base. diff --git a/content/scripts/changelog.mdx b/content/scripts/changelog.mdx index da74e536..e120f5c9 100644 --- a/content/scripts/changelog.mdx +++ b/content/scripts/changelog.mdx @@ -6,6 +6,19 @@ icon: 'clock' This page documents all changes to the NocoDB Scripts API, including new features, improvements, bug fixes, and breaking changes. +## October 22, 2025 + +#### New Input Method +- **`input.uploadFileAsync()`** - New method for uploading files + - Returns an array of `NocoDbFile` objects with file metadata + - Supports multiple file uploads simultaneously + - File type validation via `allowedFileTypes` option (MIME types, extensions, or wildcards) + - Example: `await input.uploadFileAsync("Upload images", {allowedFileTypes: ['image/*']})` + - Ideal for storing files in attachment fields. + - Complements existing `input.fileAsync()` which focuses on parsing file contents + +--- + ## October 03, 2025 #### Input Methods Enhancement diff --git a/public/img/v2/scripts/input-uploadFileAsync.png b/public/img/v2/scripts/input-uploadFileAsync.png new file mode 100644 index 00000000..75cbbc87 Binary files /dev/null and b/public/img/v2/scripts/input-uploadFileAsync.png differ