fileStorageUploadField

fileStorageUploadField allows users to upload a file to the Jmix file storage.

XML Element

fileStorageUploadField

Java Class

FileStorageUploadField

Basics

The component can contain a label, a link to the uploaded file, and an upload button. When the upload button is clicked, a standard file picker dialog pops up, allowing the user to select a file.

fileStorageUploadField can work both without being bound to an entity attribute and with data binding.

Below we will show an example of using the component without data binding. You can use it to handle the uploaded file directly without associating it with any Jmix entity.

<fileStorageUploadField id="fileRefField"
                        acceptedFileTypes=".txt, .csv"
                        fileStoragePutMode="MANUAL"
                        fileNameVisible="true"/>

Then you can handle the uploaded file directly within the FileUploadSucceededEvent.

To store a file in an entity attribute as a byte array instead of FileRef, use the fileUploadField component.

To upload multiple files simultaneously, you should use the upload component instead of fileStorageUploadField.
Internally, fileStorageUploadField uses Vaadin’s UploadHandler API. By default, the uploaded file is immediately stored in the default FileStorage. To control the saving of the file programmatically, use the fileStoragePutMode attribute.

Data-aware fileStorageUploadField

LIVE DEMO

fileStorageUploadField allows users to upload a file to the file storage and link it to an entity attribute as a FileRef object.

In the example below, the picture attribute of the User entity has the FileRef type.

@Column(name = "PICTURE", length = 1024)
private FileRef picture;
XML
<data>
    <instance id="documentDc" class="io.jmix.uisamples.entity.Document">
    </instance>
</data>
<layout>
    <fileStorageUploadField id="fileStorageUploadField" label="Select File"
                            dataContainer="documentDc" property="content"
                            fileNameVisible="false"
                            dropAllowed="true"
                            maxFileSize="51200"
                            fileStoragePutMode="MANUAL"
    />
</layout>
Java
@ViewComponent
private FileStorageUploadField fileStorageUploadField;

@Autowired
private TemporaryStorage temporaryStorage;
@Autowired
private Notifications notifications;

// This handler is needed only when fileStoragePutMode="MANUAL".
// In AUTO mode the field automatically moves the uploaded file from temporary storage
// to the FileStorage and sets the returned FileRef to the entity attribute.
@Subscribe("fileStorageUploadField")
public void onFileStorageUploadFieldFileUploadSucceeded(
        final FileUploadSucceededEvent<FileStorageUploadField, TemporaryStorage.FileInfo> event) {
    UUID fileId = event.getData().getId();
    File file = temporaryStorage.getFile(fileId);

    if (file != null) {
        FileRef fileRef = new FileRef("tempStorage", file.getAbsolutePath(), file.getName());
        fileStorageUploadField.setValue(fileRef);
        notifications.create("Your file %s has been uploaded successfully.".formatted(event.getFileName()))
                .withThemeVariant(NotificationVariant.LUMO_PRIMARY)
                .show();

        // Remove the uploaded file.
        // In a real-world application you would move the file to FileStorage here using
        // the temporaryStorage.putFileIntoStorage() method.
        temporaryStorage.deleteFile(fileId);
    }
}

fileStorageUploadField has a link to the container specified in the dataContainer attribute; the property attribute contains the name of the entity attribute that is displayed in fileStorageUploadField.

Attributes

The following attributes are specific to fileStorageUploadField:

Name Description Default

acceptedFileTypes

Specifies the types of files that the server accepts.

—

clearButtonAriaLabel

Sets the aria-label attribute to the clear button.

—

clearButtonVisible

Controls whether the field displays a clear button.

false

connectingStatusText

Sets the status shown while the upload dialog connects.

—

dropAllowed

Sets whether the component supports dropping files for uploading.

—

fileNameVisible

The fileNameVisible attribute controls whether the name of the uploaded file is displayed next to the upload button.

—

fileNotSelectedText

Sets the text shown when no file has been selected.

—

fileStorageName

Sets the name of FileStorage where the upload file will be placed.

—

fileStoragePutMode

Sets mode which determines when a file will be put into FileStorage.

—

fileTooBigText

Sets the message shown when a file exceeds the maximum size.

—

incorrectFileTypeText

Sets the message shown when a file type is not accepted.

—

maxFileSize

Specifies the maximum file size in bytes allowed for upload.

—

processingStatusText

Sets the status shown while the uploaded file is processed.

—

remainingTimeText

Sets the text used to display the remaining upload time.

—

remainingTimeUnknownText

Sets the text shown when the remaining upload time cannot be calculated.

—

uploadDialogCancelText

Sets the text of the upload dialog’s cancel button.

—

uploadDialogTitle

Sets the title of the upload dialog.

—

uploadIcon

Sets an icon to the upload button.

—

uploadText

Sets the text shown on the upload button.

—

The following shared attributes are supported by fileStorageUploadField:

id - alignSelf - classNames - colspan - css - dataContainer - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - visible - width

Handlers

The following handlers are specific to fileStorageUploadField:

Name Description

FileUploadFailedEvent

io.jmix.flowui.kit.component.upload.event.FileUploadFailedEvent is fired when a FailedEvent is triggered by the underlying Upload component.

FileUploadFileRejectedEvent

io.jmix.flowui.kit.component.upload.event.FileUploadFileRejectedEvent is fired when the underlying Vaadin Upload component triggers a FileRejectedEvent.

FileUploadFinishedEvent

io.jmix.flowui.kit.component.upload.event.FileUploadFinishedEvent is triggered when the underlying Vaadin Upload component fires a FinishedEvent.

FileUploadProgressEvent

io.jmix.flowui.kit.component.upload.event.FileUploadProgressEvent is fired when the underlying Vaadin Upload component emits a ProgressUpdateEvent.

FileUploadStartedEvent

io.jmix.flowui.kit.component.upload.event.FileUploadStartedEvent is fired when the underlying Vaadin Upload component emits a StartedEvent.

FileUploadSucceededEvent

io.jmix.flowui.kit.component.upload.event.FileUploadSucceededEvent is fired when the underlying Vaadin Upload component triggers a SucceededEvent.

validator

Validates the component value.

The following shared handlers are supported by fileStorageUploadField:

AttachEvent - ComponentValueChangeEvent - DetachEvent - statusChangeHandler

Elements

A fileStorageUploadField can include tooltip and uploadIcon as its nested elements.