Skip to content

File Handling Runtime

Custom web widgets can use the shared AltiKare.UI.File helpers for uploads, drop/paste handling, and file selection. The form-level contracts are documented in File, FileList, and ImageUpload.

File Selection Events

AltiKare.UI.FileDialog defaults to a single selection. It emits selected(file); the consuming widget decides when to close the dialog.

1
2
3
4
5
6
const dialog = new AltiKare.UI.FileDialog({accept : '.pdf'});
dialog.on('selected', file => {
    console.log(file.id, file.name);
    dialog.close();
});
dialog.show();

For batch consumers, set multiple : true. maxFiles is the limit for that dialog's new selection; subtract existing attachments when opening it. The dialog emits selectedFiles(files) when Add Selected Files is accepted and closes after the asynchronous handler completes successfully.

1
2
3
4
5
const dialog = new AltiKare.UI.FileDialog({multiple : true, maxFiles : 5});
dialog.on('selectedFiles', files => {
    console.log(files.map(file => file.id));
});
dialog.show();

Do not change existing scalar handlers to expect arrays. File and ImageUpload keep selected(file) behavior; FileList opts into the batch contract. A source can emit individual files repeatedly even when the consumer supports a batch.

Useful options include accept, initialSource, initialFiles, disabledServices, imagesOnly, compression, and reviewImage. Built-in source identifiers include Recent, Desktop, and Webcam; provider identifiers depend on configuration. A dialog opened with local initialFiles activates Desktop so progress and errors are visible. Without initial files or an explicit source, Recently Used is first when available. It is omitted for localOnly operation or when the client disables file reading. localOnly reads one local text file and returns name, content, mimeType, and size without uploading; it does not produce a stored file ID.

Upload Helpers

AltiKare.UI.File.upload(file, options) returns {promise, abort}. It uses native browser APIs and a shared queue with up to three active jobs. Each file receives its own upload link and HTTP request. Call abort() to cancel a waiting or active job; cancellation rejects with AbortError.

A successful native upload returns id, name, url, mimeType, size, and revisioned : true. With image review requested, imageReviewed marks that confirmation has completed. Source providers may return less metadata: normalize stored IDs through AltiKare.UI.File.prepareFileOptions when a URL is required, and do not assume every cloud selection has an application-owned ID or locally stored bytes.

AltiKare.UI.File.UploadList adds per-file progress, removal, retry, and a selected callback. Completed rows are removed; failed rows retain their error. Rejected file types, virus detection, and nonretryable image failures do not offer retry. FileDialog allows successfully selected files to be accepted once pending work ends, even if another transfer failed. Other consumers can require failed rows to be cleared before their own submit action.

bindInput(element, receive, enabled) returns an unbind function for drop/paste listeners. Only the closest explicitly marked file-input surface consumes file data; ordinary text paste is left to its editor. Invoke the unbind function and dispose upload lists when the owning widget is disposed. Use readClipboard() for supported clipboard image formats; keyboard paste can also expose files through the browser's clipboard event.

Image Processing

ui.imageeditor.js supplies preview, validation, crop/rotation, and compression helpers. ImageUpload requests review before native upload; its stored/template selections use a preview-only confirmation. Cancelling review must not bind a new form value. The shared HtmlBox upload adapter uses image validation and upload progress without ImageUpload's review dialog. See ImageUpload for preset behavior and limits.

The runtime uses native XHR, media capture, image decoding, and canvas operations. The legacy WebcamJS dependency has been removed. Browser camera capture uses getUserMedia; the existing Cordova camera path is retained. Feature and permission availability still depend on the browser or device.

Recent-File Responsibilities

The getRecent, removeRecent, and reuseRecent RPC operations require file-read scope. Reuse additionally requires file-write scope and creates an independent temporary copy. A recent reference is not an authorization grant: the server checks both the current domain and file owner. Removing a history reference does not delete file content.

Application.RecentItems is the manager entry point. RecentItemsManager.Files.cs contains file-history business rules, including access, expiry, limits, reuse, and revision reconciliation. RecentItemsDatabase contains the database operations. File history is accessed through this manager rather than a separate RecentFilesManager.

History keeps item type 1001 for file references. Publishing a revision merges the original and revision history into one canonical file reference, retaining the most recent recorded use. Subsequent limit pruning must not remove that new reference through an older duplicate. The temporary copy created by reuse receives a fresh creation date.

Compatibility and Enforcement

  • File and ImageUpload retain scalar file values, Caption/NameXPath, URL, and per-file revision attributes.
  • FileList introduces a collection explicitly; it does not reinterpret existing scalar XML.
  • Required validation for FileList examines live file items. Other required controls keep their existing scalar checks.
  • Picker acceptance, image limits, and MaxFiles are client behavior. Enforce required business limits and authorization in the server paths that consume the form or file.
  • Client progress and successful upload do not mean the form or workflow task has been saved or completed.