Package com.smartgwt.client.widgets.form.fields

Class FileUploadItem

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.core.RefDataClass
com.smartgwt.client.data.Field
com.smartgwt.client.widgets.form.fields.FormItem
com.smartgwt.client.widgets.form.fields.CanvasItem
com.smartgwt.client.widgets.form.fields.FileUploadItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowContextMenuHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers
public class FileUploadItem extends CanvasItem
FormItem for uploading files using HTML5 file drop capabilities.

A FileUploadItem's canvas is a FileDropZone. The value of a FileUploadItem is the JavaScript File object(s) representing files the user added.

FileUploadItem is not the default for binary type fields. To use FileUploadItem for binary fields, set DynamicForm.useFileUploadItem to true on the form, or specify editorType:"FileUploadItem" on the field.

When the form is saved, files are uploaded automatically. Use DynamicForm.showUploadProgress to display upload progress.

Single File Upload

With the default setting of multiple:false, a FileUploadItem allows uploading a single file to a binary field on the DataSource. This is analogous to the standard FileItem.

Multiple File Upload

To upload multiple files, set multiple:true and configure a DataSource property pointing to a related DataSource that will store the files. This follows the same master-detail pattern as MultiFileItem:

  • The form's DataSource is the "master" record (e.g., an email message)
  • The FileUploadItem's DataSource is the "detail" DataSource storing files (e.g., email attachments)
  • The detail DataSource must have a foreignKey linking to the master DataSource's primary key
  • Each uploaded file creates a separate record in the detail DataSource

See MultiFileItem for an example of the DataSource setup required.

Multiple Binary Fields

A form can contain multiple FileUploadItems for different binary fields in the same DataSource. When the form is saved, all files are uploaded in a single request, creating one record with all binary fields populated. This differs from FileItem which has a limitation preventing multiple file uploads in a single form submission.

Note: If you want immediate upload on drop (like Gmail attachments), use a FormItem.changed() handler to call DynamicForm.saveData().

  • Constructor Details

    • FileUploadItem

      public FileUploadItem()

    • FileUploadItem

      public FileUploadItem(JavaScriptObject jsObj)

    • FileUploadItem

      public FileUploadItem(String name)

    • FileUploadItem

      public FileUploadItem(String name, String title)

  • Method Details

    • getOrCreateRef

      public static FileUploadItem getOrCreateRef(JavaScriptObject jsObj)

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changePickerIconDefaults

      public static void changePickerIconDefaults(FormItemIcon defaults)

    • setAcceptedFileTypes

      public FileUploadItem setAcceptedFileTypes(String... acceptedFileTypes)
      See FileDropZone.acceptedFileTypes.
      Parameters:
      acceptedFileTypes - New acceptedFileTypes value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getAcceptedFileTypes

      public String[] getAcceptedFileTypes()
      See FileDropZone.acceptedFileTypes.
      Returns:
      Current acceptedFileTypes value. Default value is null

    • setCanAddFilesOnClick

      public FileUploadItem setCanAddFilesOnClick(Boolean canAddFilesOnClick)
      See FileDropZone.canAddFilesOnClick.
      Parameters:
      canAddFilesOnClick - New canAddFilesOnClick value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getCanAddFilesOnClick

      public Boolean getCanAddFilesOnClick()
      See FileDropZone.canAddFilesOnClick.
      Returns:
      Current canAddFilesOnClick value. Default value is null

    • setCancelButtonTitle

      public FileUploadItem setCancelButtonTitle(String cancelButtonTitle)
      Custom cancelButtonTitle for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      cancelButtonTitle - New cancelButtonTitle value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getCancelButtonTitle

      public String getCancelButtonTitle()
      Custom cancelButtonTitle for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current cancelButtonTitle value. Default value is null

    • getCanvas

      public FileDropZone getCanvas()
      The FileDropZone component that provides the drag-drop file selection UI.

      The FileDropZone is automatically created using the canvasConstructor and canvasDefaults properties. To customize the FileDropZone, either set properties directly on the FileUploadItem (which are passed through to the FileDropZone) or override canvasDefaults.

      Access the FileDropZone via fileUploadItem.canvas after the item is created.

      This component is an AutoChild named "canvas". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Overrides:
      getCanvas in class CanvasItem
      Returns:
      Current canvas value. Default value is null

    • setCanvasConstructor

      public FileUploadItem setCanvasConstructor(String canvasConstructor)
      The class to use for the Canvas autoChild. Default is FileDropZone.
      Parameters:
      canvasConstructor - New canvasConstructor value. Default value is "FileDropZone"
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getCanvasConstructor

      public String getCanvasConstructor()
      The class to use for the Canvas autoChild. Default is FileDropZone.
      Returns:
      Current canvasConstructor value. Default value is "FileDropZone"

    • setCanvasDefaults

      public FileUploadItem setCanvasDefaults(Map canvasDefaults)
      Default properties for the Canvas autoChild FileDropZone.

      The default implementation includes handlers that forward FileDropZone.filesAdded() and FileDropZone.filesRemoved() notifications to update the FormItem's value.

      When overriding, use isc.addProperties() to merge with the defaults rather than replacing them entirely, to preserve the value synchronization behavior.

      Parameters:
      canvasDefaults - New canvasDefaults value. Default value is {...}
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getCanvasDefaults

      public Map getCanvasDefaults()
      Default properties for the Canvas autoChild FileDropZone.

      The default implementation includes handlers that forward FileDropZone.filesAdded() and FileDropZone.filesRemoved() notifications to update the FormItem's value.

      When overriding, use isc.addProperties() to merge with the defaults rather than replacing them entirely, to preserve the value synchronization behavior.

      Returns:
      Current canvasDefaults value. Default value is {...}

    • setClickToAddMessage

      public FileUploadItem setClickToAddMessage(String clickToAddMessage)
      Custom clickToAddMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      clickToAddMessage - New clickToAddMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getClickToAddMessage

      public String getClickToAddMessage()
      Custom clickToAddMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current clickToAddMessage value. Default value is null

    • setDataSource

      public FileUploadItem setDataSource(DataSource dataSource)
      DataSource where files are stored when multiple:true.

      This DataSource should contain:

      • A primaryKey field
      • A field with a foreignKey relationship to the primary key of the form's DataSource
      • A field of type "binary" for storing the uploaded file

      This follows the same pattern as MultiFileItem.dataSource. See MultiFileItem for a complete example of the required DataSource structure.

      This property is required when multiple:true is set. If omitted, a warning will be logged and the item will behave as single-file upload.

      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getDataSource

      public DataSource getDataSource()
      DataSource where files are stored when multiple:true.

      This DataSource should contain:

      • A primaryKey field
      • A field with a foreignKey relationship to the primary key of the form's DataSource
      • A field of type "binary" for storing the uploaded file

      This follows the same pattern as MultiFileItem.dataSource. See MultiFileItem for a complete example of the required DataSource structure.

      This property is required when multiple:true is set. If omitted, a warning will be logged and the item will behave as single-file upload.

      Returns:
      Returns the DataSource configured for storing uploaded files when multiple:true. Default value is null

    • setDataSource

      public FileUploadItem setDataSource(String dataSource)
      DataSource where files are stored when multiple:true.

      This DataSource should contain:

      • A primaryKey field
      • A field with a foreignKey relationship to the primary key of the form's DataSource
      • A field of type "binary" for storing the uploaded file

      This follows the same pattern as MultiFileItem.dataSource. See MultiFileItem for a complete example of the required DataSource structure.

      This property is required when multiple:true is set. If omitted, a warning will be logged and the item will behave as single-file upload.

      Parameters:
      dataSource - New dataSource value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getDataSourceAsString

      public String getDataSourceAsString()
      DataSource where files are stored when multiple:true.

      This DataSource should contain:

      • A primaryKey field
      • A field with a foreignKey relationship to the primary key of the form's DataSource
      • A field of type "binary" for storing the uploaded file

      This follows the same pattern as MultiFileItem.dataSource. See MultiFileItem for a complete example of the required DataSource structure.

      This property is required when multiple:true is set. If omitted, a warning will be logged and the item will behave as single-file upload.

      Returns:
      Returns the DataSource configured for storing uploaded files when multiple:true. Default value is null

    • setDuplicateFileNameMessage

      public FileUploadItem setDuplicateFileNameMessage(String duplicateFileNameMessage)
      Custom duplicateFileNameMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      duplicateFileNameMessage - New duplicateFileNameMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getDuplicateFileNameMessage

      public String getDuplicateFileNameMessage()
      Custom duplicateFileNameMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current duplicateFileNameMessage value. Default value is null

    • setEmptyDropAreaMessage

      public FileUploadItem setEmptyDropAreaMessage(String emptyDropAreaMessage)
      Custom emptyDropAreaMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      emptyDropAreaMessage - New emptyDropAreaMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getEmptyDropAreaMessage

      public String getEmptyDropAreaMessage()
      Custom emptyDropAreaMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current emptyDropAreaMessage value. Default value is null

    • setInvalidFileTypeMessage

      public FileUploadItem setInvalidFileTypeMessage(String invalidFileTypeMessage)
      Custom invalidFileTypeMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      invalidFileTypeMessage - New invalidFileTypeMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getInvalidFileTypeMessage

      public String getInvalidFileTypeMessage()
      Custom invalidFileTypeMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current invalidFileTypeMessage value. Default value is null

    • setMaxFiles

      public FileUploadItem setMaxFiles(Integer maxFiles)
      See FileDropZone.maxFiles.
      Parameters:
      maxFiles - New maxFiles value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxFiles

      public Integer getMaxFiles()
      See FileDropZone.maxFiles.
      Returns:
      Current maxFiles value. Default value is null

    • setMaxFilesErrorMessage

      public FileUploadItem setMaxFilesErrorMessage(String maxFilesErrorMessage)
      Custom maxFilesErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      maxFilesErrorMessage - New maxFilesErrorMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxFilesErrorMessage

      public String getMaxFilesErrorMessage()
      Custom maxFilesErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current maxFilesErrorMessage value. Default value is null

    • setMaxFileSize

      public FileUploadItem setMaxFileSize(Integer maxFileSize)
      See FileDropZone.maxFileSize.
      Parameters:
      maxFileSize - New maxFileSize value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxFileSize

      public Integer getMaxFileSize()
      See FileDropZone.maxFileSize.
      Returns:
      Current maxFileSize value. Default value is null

    • setMaxFileSizeErrorMessage

      public FileUploadItem setMaxFileSizeErrorMessage(String maxFileSizeErrorMessage)
      Custom maxFileSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      maxFileSizeErrorMessage - New maxFileSizeErrorMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxFileSizeErrorMessage

      public String getMaxFileSizeErrorMessage()
      Custom maxFileSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current maxFileSizeErrorMessage value. Default value is null

    • setMaxSize

      public FileUploadItem setMaxSize(Integer maxSize)
      See FileDropZone.maxSize.
      Parameters:
      maxSize - New maxSize value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxSize

      public Integer getMaxSize()
      See FileDropZone.maxSize.
      Returns:
      Current maxSize value. Default value is null

    • setMaxSizeErrorMessage

      public FileUploadItem setMaxSizeErrorMessage(String maxSizeErrorMessage)
      Custom maxSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      maxSizeErrorMessage - New maxSizeErrorMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMaxSizeErrorMessage

      public String getMaxSizeErrorMessage()
      Custom maxSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current maxSizeErrorMessage value. Default value is null

    • setMinSize

      public FileUploadItem setMinSize(Integer minSize)
      See FileDropZone.minSize.
      Parameters:
      minSize - New minSize value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMinSize

      public Integer getMinSize()
      See FileDropZone.minSize.
      Returns:
      Current minSize value. Default value is null

    • setMinSizeErrorMessage

      public FileUploadItem setMinSizeErrorMessage(String minSizeErrorMessage)
      Custom minSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      minSizeErrorMessage - New minSizeErrorMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMinSizeErrorMessage

      public String getMinSizeErrorMessage()
      Custom minSizeErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current minSizeErrorMessage value. Default value is null

    • setMultiple

      public FileUploadItem setMultiple(Boolean multiple)
      Whether this FileUploadItem allows multiple files to be selected.

      When multiple:true, a DataSource property must also be specified pointing to a related DataSource that will store the uploaded files, following the same master-detail pattern as MultiFileItem. Each file will be uploaded as a separate record in the detail DataSource after the master record is saved.

      If multiple:true is set without a valid DataSource, a warning will be logged and the item will behave as if multiple:false.

      See FileDropZone.multiple for the underlying FileDropZone property.

      Overrides:
      setMultiple in class CanvasItem
      Parameters:
      multiple - New multiple value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls
      See Also:

    • getMultiple

      public Boolean getMultiple()
      Whether this FileUploadItem allows multiple files to be selected.

      When multiple:true, a DataSource property must also be specified pointing to a related DataSource that will store the uploaded files, following the same master-detail pattern as MultiFileItem. Each file will be uploaded as a separate record in the detail DataSource after the master record is saved.

      If multiple:true is set without a valid DataSource, a warning will be logged and the item will behave as if multiple:false.

      See FileDropZone.multiple for the underlying FileDropZone property.

      Overrides:
      getMultiple in class CanvasItem
      Returns:
      Current multiple value. Default value is null
      See Also:

    • setMultipleFilesErrorMessage

      public FileUploadItem setMultipleFilesErrorMessage(String multipleFilesErrorMessage)
      Custom multipleFilesErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      multipleFilesErrorMessage - New multipleFilesErrorMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getMultipleFilesErrorMessage

      public String getMultipleFilesErrorMessage()
      Custom multipleFilesErrorMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current multipleFilesErrorMessage value. Default value is null

    • setProcessingMessage

      public FileUploadItem setProcessingMessage(String processingMessage)
      Custom processingMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Parameters:
      processingMessage - New processingMessage value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getProcessingMessage

      public String getProcessingMessage()
      Custom processingMessage for this fileUploadItem's canvas. If unset, the default property will be used.
      Returns:
      Current processingMessage value. Default value is null

    • setReplaceFilesOnDrop

      public FileUploadItem setReplaceFilesOnDrop(Boolean replaceFilesOnDrop)
      See FileDropZone.replaceFilesOnDrop.
      Parameters:
      replaceFilesOnDrop - New replaceFilesOnDrop value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getReplaceFilesOnDrop

      public Boolean getReplaceFilesOnDrop()
      See FileDropZone.replaceFilesOnDrop.
      Returns:
      Current replaceFilesOnDrop value. Default value is null

    • setShowCancelButton

      public FileUploadItem setShowCancelButton(Boolean showCancelButton)
      See FileDropZone.showCancelButton.
      Parameters:
      showCancelButton - New showCancelButton value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getShowCancelButton

      public Boolean getShowCancelButton()
      See FileDropZone.showCancelButton.
      Returns:
      Current showCancelButton value. Default value is null

    • setShowFileThumbnails

      public FileUploadItem setShowFileThumbnails(Boolean showFileThumbnails)
      See FileDropZone.showFileThumbnails.
      Parameters:
      showFileThumbnails - New showFileThumbnails value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getShowFileThumbnails

      public Boolean getShowFileThumbnails()
      See FileDropZone.showFileThumbnails.
      Returns:
      Current showFileThumbnails value. Default value is null

    • setShowImagePreviews

      public FileUploadItem setShowImagePreviews(Boolean showImagePreviews)
      See FileDropZone.showImagePreviews.
      Parameters:
      showImagePreviews - New showImagePreviews value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getShowImagePreviews

      public Boolean getShowImagePreviews()
      See FileDropZone.showImagePreviews.
      Returns:
      Current showImagePreviews value. Default value is null

    • setThumbnailHeight

      public FileUploadItem setThumbnailHeight(Integer thumbnailHeight)
      See FileDropZone.thumbnailHeight.
      Parameters:
      thumbnailHeight - New thumbnailHeight value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getThumbnailHeight

      public Integer getThumbnailHeight()
      See FileDropZone.thumbnailHeight.
      Returns:
      Current thumbnailHeight value. Default value is null

    • setThumbnailWidth

      public FileUploadItem setThumbnailWidth(Integer thumbnailWidth)
      See FileDropZone.thumbnailWidth.
      Parameters:
      thumbnailWidth - New thumbnailWidth value. Default value is null
      Returns:
      FileUploadItem instance, for chaining setter calls

    • getThumbnailWidth

      public Integer getThumbnailWidth()
      See FileDropZone.thumbnailWidth.
      Returns:
      Current thumbnailWidth value. Default value is null

    • cancelProcessing

      public void cancelProcessing()
      See FileDropZone.cancelProcessing().

    • endProcessing

      public void endProcessing()
      See FileDropZone.endProcessing().

    • getFiles

      public void getFiles()
      See FileDropZone.getFiles().

    • getSize

      public void getSize()
      See FileDropZone.getSize().

    • setFileProgress

      public void setFileProgress()
      See FileDropZone.setFileProgress().

    • setProcessingProgress

      public void setProcessingProgress()
      See FileDropZone.setProcessingProgress().

    • startProcessing

      public void startProcessing()
      See FileDropZone.startProcessing().

    • setDefaultProperties

      public static void setDefaultProperties(FileUploadItem fileUploadItemProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      fileUploadItemProperties - properties that should be used as new defaults when instances of this class are created
      See Also: