FileUploadField is automatically used inside FieldGroup for entity attributes of type FileDescriptor. In this case, the field looks as shown above and does not require additional configuration. An uploaded file is immediately stored in file storage and the corresponding FileDescriptor instance is saved to the database.

You can use the component outside FieldGroup and connect it to a datasource. For example, here we suppose that the personDs datasource contains an entity with the photo attribute which is a reference to FileDescriptor:

<upload fileStoragePutMode="IMMEDIATE"
        datasource="personDs"
        property="photo"/>

You can also control the saving of file and FileDescriptor programmatically.

In the screen controller, inject the component itself, the FileUploadingAPI and DataSupplier interfaces. In the init() method, add listeners which will react on successful uploads and errors:

@Inject
private FileUploadField uploadField;
@Inject
private FileUploadingAPI fileUploadingAPI;
@Inject
private DataSupplier dataSupplier;

@Override
public void init(Map<String, Object> params) {
    uploadField.addFileUploadSucceedListener(event -> {
        FileDescriptor fd = uploadField.getFileDescriptor();
        try {
            // save file to FileStorage
            fileUploadingAPI.putFileIntoStorage(uploadField.getFileId(), fd);
        } catch (FileStorageException e) {
            throw new RuntimeException("Error saving file to FileStorage", e);
        }
        // save file descriptor to database
        dataSupplier.commit(fd);
        showNotification("Uploaded file: " + uploadField.getFileName(), NotificationType.HUMANIZED);
    });

    uploadField.addFileUploadErrorListener(event ->
            showNotification("File upload error", NotificationType.HUMANIZED));
}

The fileStoragePutMode XML attribute defines how the file and the corresponding FileDescriptor are stored. In the IMMEDIATE mode it is done right after uploading file to the temporary storage of the client tier. In the MANUAL mode, you should do it programmatically in a FileUploadSucceedListener. The IMMEDIATE mode is selected by default when FileUploadField is used inside FieldGroup. Otherwise, the default mode is MANUAL.

The uploadButtonCaption, uploadButtonIcon and uploadButtonDescription XML attributes allows you to set the properties of the upload button.

The showFileName XML attribute controls whether the name of uploaded file is displayed next to upload button. It is false by default.

The showClearButton XML attribute controls whether the clear button is visible. It is false by default.

The clearButtonCaption, clearButtonIcon and clearButtonDescription XML attributes allows you to set the properties of the clear button if it is visible.

The accept XML attribute (and the corresponding setAccept() method) can be used to set the file type mask in the file selection dialog. Users still be able to change the mask to "All files" and upload arbitrary files.

Maximum upload size is determined by the cuba.maxUploadSizeMb application property and is 20MB by default. If a user selects a file of a larger size, a corresponding message will be displayed, and the upload will be interrupted.

The fileSizeLimit XML attribute (and the corresponding setFileSizeLimit() method) can be used to set maximum allowed file size specified in bytes.

<upload id="uploadField" fileSizeLimit="2000"/>

The permittedExtensions XML attribute (and the corresponding setPermittedExtensions() method) sets the white list of permitted file extensions.

uploadField.setPermittedExtensions(Sets.newHashSet(".png", ".jpg"));

The dropZone XML attribute allows you to specify a BoxLayout to be used as a target for drag-and-dropping files from outside of the browser. The dropZone can cover the whole layout of a dialog window. The selected container is highlighted when a user drags a file over the container, otherwise it is not visible.

<layout spacing="true"
        width="100%">
    <vbox id="dropZone"
          height="AUTO"
          spacing="true">
        <textField id="textField"
                   caption="Title"
                   width="100%"/>
        <textArea id="textArea"
                  caption="Description"
                  width="100%"
                  rows="5"/>
        <checkBox caption="Is reference document"
                  width="100%"/>
        <upload id="upload"
                dropZone="dropZone"
                showClearButton="true"
                showFileName="true"/>
    </vbox>
    <hbox spacing="true">
        <button caption="mainMsg://actions.Apply"/>
        <button caption="mainMsg://actions.Cancel"/>
    </hbox>
</layout>

<layout spacing="true"
        width="100%">
    <textField id="textField"
               caption="Title"
               width="100%"/>
    <checkBox caption="Is reference document"
              width="100%"/>
    <upload id="upload"
            dropZone="dropZone"
            showClearButton="true"
            showFileName="true"/>
    <vbox id="dropZone"
          height="150px"
          spacing="true"
          stylename="dropzone-container">
        <label stylename="dropzone-description"
               value="Drop file here"
               align="MIDDLE_CENTER"/>
    </vbox>
    <hbox spacing="true">
        <button caption="mainMsg://actions.Apply"/>
        <button caption="mainMsg://actions.Cancel"/>
    </hbox>
</layout>