MXT Universal File Dropper: A Unified File Upload and Document Management Experience in Mendix

A reusable Mendix pluggable widget for file upload, validation, preview, image editing, document scanning, and Mendix FileDocument management

Redefining File Management in Mendix Applications

Enterprise Mendix applications often need much more than a basic file upload control. Users may need to upload multiple files, validate them, preview different formats, edit images, scan documents from a mobile device, manage upload progress, and work with the resulting Mendix FileDocument records.

MXT Universal File Dropper provides a reusable approach to these requirements. Instead of creating separate upload, preview, image-editing, and document-management experiences for every application, the widget brings these capabilities together while preserving the existing Mendix data-source, association, action, and upload architecture.

Understanding the MXT Universal File Dropper

The widget is designed around a complete file-processing pipeline. A user can select or drop one or multiple files, pass them through validation, optionally edit images, and then upload the final files through the configured Mendix workflow.

Select / Drop → Validate → Edit Image (if applicable) → Final Validation → Upload Queue → Mendix FileDocument

[Figure 1. Universal File Dropper workflow]

Core File Upload Capabilities

The widget combines the common upload requirements into one reusable component:

· Drag-and-drop file selection

· Standard file picker

· Single and multiple file uploads

· Configurable concurrent uploads

· Upload progress

· Retry and cancel operations

· Duplicate-name validation

· Minimum and maximum file-size validation

· File-count validation

· Extension and MIME-type validation

· File-signature validation where applicable

· Offline/PWA-aware upload handling

File Type Icons and Metadata

Managing a large collection of uploaded files becomes easier when users can identify file types at a glance. The widget provides visual file-type indicators for common formats such as PDF, Word, Excel, ZIP, images, video, audio, and generic documents.

The document presentation can also show useful metadata such as file name, file size, MIME type, and image dimensions where applicable. This gives users useful information without opening every file.

[Figure 2. File list with file-type icons and metadata]

Previewing Uploaded Files

A major part of the widget is its preview experience. Common file categories can be displayed without forcing users to leave the current Mendix page.

· Image preview with zoom

· Full-screen image preview

· PDF preview

· Spreadsheet preview

· Text preview

· JSON preview

· XML preview

· Video and audio playback where browser support is available

The preview layer remains integrated with the document list, so users can preview a document while continuing to use actions such as select, download, rename, or delete.

Client-Side Image Editing Before Upload

Images often need to be prepared before they are uploaded. MXT Universal File Dropper adds an optional client-side editing stage so the browser can process the image before the final upload begins.

· Free-form crop with live preview

· Clockwise and counter-clockwise 90° rotation

· Resize by width and height

· Optional aspect-ratio preservation

· Compression quality control

· JPEG, PNG and WebP output where supported by the browser

· Final width and height display

· Final file-size display

· Apply, Cancel and Reset controls

The original browser File is never mutated. Editing produces a new File/Blob only after the user confirms the changes. The resulting file is then sent through the existing validation pipeline again.

Final File Validation

Image editing can change the final dimensions and file size. For that reason, validation is performed again after editing so that the upload queue always receives the actual file that will be uploaded.

Original File → Edit → Generate Final File → Validate Final File → Upload

Document Scanner Mode for PWA

For mobile and PWA scenarios, the widget can extend file acquisition beyond traditional file selection by providing a document-scanning workflow.

· Camera-based document capture

· Document-edge detection

· Automatic crop

· Perspective correction

· Rotation

· Image enhancement

· Multi-page scanning

· Combining scanned pages into PDF/JPG output

· Uploading the resulting document through the existing queue

This is particularly useful for invoices, receipts, forms, field-service documents, and other paper-based content that needs to enter a Mendix application.

[Figure 3. PWA document scanner workflow]

Working with Mendix FileDocument Objects

One of the important architectural goals is to keep the widget Mendix-native. Uploaded files are represented by actual Mendix FileDocument objects rather than strings, JSON objects, document names, or GUID values.

When multiple files are uploaded, each file follows its own creation and upload path:

File 1 → Create FileDocument → Associate with parent → Upload → Commit

File 2 → Create FileDocument → Associate with parent → Upload → Commit

File 3 → Create FileDocument → Associate with parent → Upload → Commit

The parent object and association remain configured through the proper Studio Pro property mechanisms. The developer does not need to manually type entity or association names into string properties.

Displaying a Mendix Document List

For applications that manage multiple documents, the widget can work with a Mendix list data source. The list data source remains the source of truth, allowing the widget to display the actual documents associated with the current business object.

Parent Object → Mendix Document List → Widget Document List

This architecture avoids maintaining a separate JavaScript-only list of fake documents. When documents are created, committed, renamed, or deleted, the Mendix data source can refresh and the widget reflects the current state.

Document Selection

Users can select an uploaded document directly from the list. The selected item is represented using the supported Mendix object/list APIs and can be passed to a configured Mendix action where supported.

User clicks contract.pdf

↓

Widget identifies the selected Mendix document

↓

Visual selection state is updated

↓

Configured Document Selected action executes

↓

Mendix logic receives the actual Document object

Direct Document Actions

A document-management experience should make common actions immediately available. The widget can provide controls for:

· Select

· Preview

· Download

· Rename

· Delete

· Retry failed upload

· Cancel active upload

Deletion is handled through supported Mendix mechanisms rather than simply removing an item from a browser array. Once the actual Mendix object is deleted and the data source refreshes, the document disappears from the list.

Configuring the Widget

Setting

Purpose

Allow Upload

Controls whether users can select and upload files.

Create File Record

Configures the Mendix nanoflow used to create a FileDocument record.

Concurrent Uploads

Controls how many files can upload at the same time.

Upload Immediately

Starts uploading files as soon as they pass validation.

Enable Image Editing

Enables the image-editing stage before upload.

Crop / Rotate / Resize

Controls individual image-editing capabilities.

Compression Quality

Defines the default image compression quality.

Document Data Source

Provides the Mendix document list displayed by the widget.

Document Selected Action

Runs Mendix logic when a document is selected.

Delete Action

Controls the supported Mendix deletion behavior.

Web, Mobile and PWA Support

The widget is designed to work across desktop web, tablet, and mobile/PWA interfaces. The UI should remain responsive and touch-friendly, while browser-dependent features such as camera capture and image processing are handled on the client where supported.

· Mouse interaction

· Touch interaction

· Responsive document list

· Mobile file picker

· Camera-based document scanning

· Offline-aware queue behavior

Recommended Architecture

The overall design keeps file processing in the widget and authoritative document persistence in Mendix.

Mendix Parent Object → File Dropper → Validation → Optional Image Editing → Upload Queue → FileDocument → Association → Commit

This separation allows the widget to provide a rich user experience without replacing Mendix's domain model, security, microflows, nanoflows, associations, or persistence mechanisms.

Why Use a Reusable Universal File Dropper?

· Centralizes file-upload functionality instead of duplicating it across pages.

· Provides a consistent validation and preview experience.

· Reduces image file size before upload through client-side processing.

· Supports richer mobile/PWA document acquisition.

· Makes multiple FileDocument management easier.

· Provides document selection and actions within the same component.

· Keeps Mendix entity and data-source configuration aligned with Studio Pro.

· Reduces development effort for applications that repeatedly need document handling.

Enterprise Use Cases

· Invoice and receipt management

· Procurement and vendor document portals

· Employee document submission

· Customer onboarding and supporting documents

· Healthcare and administrative document workflows

· Field-service photo and document capture

· Approval applications

· Contract and attachment management

· Mobile/PWA document collection

Best Practices

· Keep authoritative persistence and security on the Mendix/server side.

· Use proper Studio Pro data-source, association and action properties instead of string-based entity configuration.

· Validate the final edited image again before upload.

· Keep the original image unchanged until the user confirms editing.

· Use conservative file-signature validation because several container formats share signatures.

· Keep the Mendix document list as the source of truth.

· Test upload, retry, cancel, delete, refresh and offline scenarios on realistic devices.

· Use appropriate access rules for FileDocument entities and related microflows/nanoflows.

Conclusion

MXT Universal File Dropper provides a practical way to turn file handling into a reusable document-management experience inside Mendix applications. It combines upload, validation, preview, image editing, compression, document scanning, metadata, file-type recognition, queue management and Mendix FileDocument integration in one component.

The key architectural benefit is that these features are added around the existing Mendix workflow rather than replacing it. Developers can continue using Mendix objects, data sources, associations and actions while users get a more complete and modern document experience.

For applications that handle documents regularly, this approach can reduce repeated development work while providing a consistent experience across web and PWA environments.