File Upload Binding

FileUploadBinding provides a unified API for file selection (button or drag-drop), client-side reading, and server upload with chunked transfer and progress tracking.

Package: io-oidis-hub-gui Import: @io-oidis-hub-gui/Io/Oidis/Hub/Gui/Bindings/FileUploadBinding.js

Quick Start

import { FileUploadBinding } from "@io-oidis-hub-gui/Io/Oidis/Hub/Gui/Bindings/FileUploadBinding.js";

const fileUpload : FileUploadBinding = new FileUploadBinding();
fileUpload.Bind({
    button: $instance.selectFileButton
}, {
    onData: async ($files : FileList) : Promise<void> => {
        // Files selected — read or upload
    }
});
fileUpload.setFilter(".csv,.xlsx");

Bind

fileUpload.Bind($userControls, $handlers);

User Controls (all optional):

Control	Type	Description
button	Button	Click opens native file dialog
field	TextField	Native <input type="file"> or text field for display
progress	ProgressBar	Shows upload/read progress (0–100)
dropZone	GuiCommons	HTML element accepting drag-and-drop

Handlers:

Handler	Required	Signature
onData	Yes	($files : FileList) => Promise<void>
onEmptySelection	No	() => void
onProgressChange	No	($status : boolean) => void

When button is provided, clicking it opens the browser file dialog. The binding creates a hidden native <input type="file"> automatically — no need to add one in HTML.

When dropZone is provided, users can drag-and-drop files onto the element. Visual feedback is handled automatically (dropEffect = "copy").

Configuration

fileUpload.setFilter(".csv");              // Accept attribute (MIME or extensions)
fileUpload.setMultipleSelectEnabled(true); // Allow multi-file selection

Client-Side Reading (FE-Only)

Use Read() to get file content without uploading to server:

const contents : string[] = await fileUpload.Read();         // Base64 encoded (default)
const contents : string[] = await fileUpload.Read({
    encoded: false      // Raw UTF-8 text
});

Read Options:

Option	Default	Description
encoded	true	Base64 encode content
urlSafe	false	URL-safe base64
start / end	—	Byte range for partial reading
resetInputField	true	Clear input after reading

Custom Charset Reading

Read() uses UTF-8 by default. For files with different encoding (e.g., windows-1250 CSV from Czech systems), use TextDecoder in the onData handler:

fileUpload.Bind({
    button: $instance.selectFile
}, {
    onData: async ($files : FileList) : Promise<void> => {
        const buffer : ArrayBuffer = await $files[0].arrayBuffer();
        const decoder : TextDecoder = new TextDecoder("windows-1250");
        const content : string = decoder.decode(buffer);
    }
});

Server Upload

Use Upload() to send files to the backend in chunks:

const paths : string[] = await fileUpload.Upload("StorageName");

Files are chunked (500KB default, 250KB on Safari) and sent via FileInputConnector.Upload(). The backend FileInputHandler reassembles chunks.

Backend Retrieval

On the backend, retrieve uploaded file data using FileInputHandler:

import { FileInputHandler } from "@io-oidis-hub/Io/Oidis/Hub/IOApi/Handlers/FileInputHandler.js";

const data : Buffer = FileInputHandler.getData("StorageName_0");

getData($path, $once) — $once = true (default) deletes data after retrieval.

File Download (FileFetch)

To trigger a browser download from the frontend:

import { FileFetch } from "@io-oidis-services/Io/Oidis/Services/Utils/FileFetch.js";

await new FileFetch().Open({
    content : myBlob,
    fileName: "export.json"
});

Common Patterns

Pattern A: Read Image + Display Preview

const fileUpload : FileUploadBinding = new FileUploadBinding();
let imageData : string = "";

fileUpload.Bind({
    button: $instance.photoUploadButton
}, {
    onData: async ($files : FileList) : Promise<void> => {
        if ($files.length === 1) {
            imageData = (await fileUpload.Read())[0];
            $instance.profileImg.Source("data:image/png;base64, " + imageData);
        }
    }
});
fileUpload.setFilter(".jpg,.png");

Pattern B: Upload with Progress

const fileUpload : FileUploadBinding = new FileUploadBinding();

fileUpload.Bind({
    button  : $instance.upload,
    field   : $instance.fileSource,
    progress: $instance.uploadProgress
}, {
    onData: async ($files : FileList) : Promise<void> => {
        await fileUpload.Upload("MyFile");
        await this.client.ProcessUploadedFile($files[0].name);
    },
    onProgressChange: ($status : boolean) : void => {
        $instance.progressBar.Visible($status);
    }
});

Pattern C: CSV with Custom Charset (FE-Only)

const fileUpload : FileUploadBinding = new FileUploadBinding();
let csvContent : string = "";

fileUpload.Bind({
    button: $instance.selectCsvButton
}, {
    onData: async ($files : FileList) : Promise<void> => {
        const buffer : ArrayBuffer = await $files[0].arrayBuffer();
        const decoder : TextDecoder = new TextDecoder("windows-1250");
        csvContent = decoder.decode(buffer);
        $instance.fileNameLabel.Content($files[0].name);
    }
});
fileUpload.setFilter(".csv");

---

See also: Panels and Controllers | Events and Validation | Data Binding