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

Class FileItem

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.FileItem
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
Direct Known Subclasses:
ViewFileItem
public class FileItem extends CanvasItem
Binary data interface for use in DynamicForms. Allows users to select a single file for upload. In read-only mode (canEdit:false), can display the contents of "imageFile" fields.

Editable mode

The editForm will be automatically generated and displayed as this.canvas, allowing the user to select file(s) to upload.

See the Upload Overview for information on using this control.

Read-only mode

For fields of type "blob" the raw data value will be displayed in the generated displayForm.

For other fields, the displayCanvas will be displayed.

For "imageFile" fields with showFileInline set to true, the image-file will be streamed and displayed inline within the displayCanvas.

Otherwise, the displayCanvas will render out View and Download icons and the fileName.

See Also:

  • Constructor Details

    • FileItem

      public FileItem()

    • FileItem

      public FileItem(JavaScriptObject jsObj)

    • FileItem

      public FileItem(String name)

    • FileItem

      public FileItem(String name, String title)

  • Method Details

    • getOrCreateRef

      public static FileItem 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)

    • setAccept

      public FileItem setAccept(String accept)
      A comma-separated list of valid MIME types, used as a filter for the file picker window.

      Note that this property makes use of the HTML accept attribute, and so relies on the browser to perform the desired filtering. For further study, see:

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

    • getAccept

      public String getAccept()
      A comma-separated list of valid MIME types, used as a filter for the file picker window.

      Note that this property makes use of the HTML accept attribute, and so relies on the browser to perform the desired filtering. For further study, see:

      Returns:
      Current accept value. Default value is null

    • setCapture

      public FileItem setCapture(String capture)
      This attribute enables camera capture functionality for mobile devices, accepting the following values:
      • Set it to "user" to capture using the front-facing camera.
      • Set it to "environment" to capture using the rear-facing camera.

      Please note that in the latest versions of Android and iOS, utilizing this attribute will consistently load the rear camera. This behavior is due to the direct camera software's ability to switch between the two cameras seamlessly.

      When working with the capture functionality of iPhones and Android devices, it's important to consider the supported DataSourceField.mimeTypes for audio, video, and image files that can be used with the fileItem.accept attribute. Here's a list of commonly supported mime types for capturing on these devices:

      Supported Image Mime Types:

      • image/jpeg: JPEG image format (.jpg, .jpeg)
      • image/png: Portable Network Graphics format (.png)
      Supported Audio Mime Types:
      • audio/3gpp: 3GPP format, commonly used for audio capture.
      • audio/mp4: MP4 format, widely supported for audio capture.
      Supported Video Mime Types:
      • video/3gpp: 3GPP format, commonly used for video capture.
      • video/mp4: MP4 format, widely supported for video capture.
      Behavior Based on 'accept' Attribute

      The behavior of using the capture attribute depends on the value used in the accept attribute. For example:

      • accept="image/*" will load the camera ready to take pictures.
      • accept="audio/*" will load the default audio recorder, not the camera.
      • accept="video/*" will load the camera in video mode, ready to capture videos.
      Please note that the Smart GWT framework does not control the native device behavior beyond these attribute settings.

      Lastly, keep in mind that these settings have no effect on desktop browsers; they apply exclusively to mobile devices.

      This information is "circa 2023" and may not apply to all devices.

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

    • getCapture

      public String getCapture()
      This attribute enables camera capture functionality for mobile devices, accepting the following values:
      • Set it to "user" to capture using the front-facing camera.
      • Set it to "environment" to capture using the rear-facing camera.

      Please note that in the latest versions of Android and iOS, utilizing this attribute will consistently load the rear camera. This behavior is due to the direct camera software's ability to switch between the two cameras seamlessly.

      When working with the capture functionality of iPhones and Android devices, it's important to consider the supported DataSourceField.mimeTypes for audio, video, and image files that can be used with the fileItem.accept attribute. Here's a list of commonly supported mime types for capturing on these devices:

      Supported Image Mime Types:

      • image/jpeg: JPEG image format (.jpg, .jpeg)
      • image/png: Portable Network Graphics format (.png)
      Supported Audio Mime Types:
      • audio/3gpp: 3GPP format, commonly used for audio capture.
      • audio/mp4: MP4 format, widely supported for audio capture.
      Supported Video Mime Types:
      • video/3gpp: 3GPP format, commonly used for video capture.
      • video/mp4: MP4 format, widely supported for video capture.
      Behavior Based on 'accept' Attribute

      The behavior of using the capture attribute depends on the value used in the accept attribute. For example:

      • accept="image/*" will load the camera ready to take pictures.
      • accept="audio/*" will load the default audio recorder, not the camera.
      • accept="video/*" will load the camera in video mode, ready to capture videos.
      Please note that the Smart GWT framework does not control the native device behavior beyond these attribute settings.

      Lastly, keep in mind that these settings have no effect on desktop browsers; they apply exclusively to mobile devices.

      This information is "circa 2023" and may not apply to all devices.

      Returns:
      Current capture value. Default value is null

    • getDisplayCanvas

      public Canvas getDisplayCanvas()
      The Canvas created automatically when canEdit is false and the field is of any type other than "blob".

      If the field is of type "imageFile", and showFileInline is true, the contents of the canvas are set to HTML that streams the image file for display. Otherwise, the item renders icons that allow the file to be viewed or downloaded.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via fileItem.displayCanvasDefaults and fileItem.displayCanvasProperties.

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

      Returns:
      Current displayCanvas value. Default value is null
      See Also:

    • getDisplayForm

      public DynamicForm getDisplayForm()
      The DynamicForm created automatically when canEdit is false and the field is of type "blob". Displays a single item for viewing the content of a blob file.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via fileItem.displayFormDefaults and fileItem.displayFormProperties.

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

      Returns:
      Current displayForm value. Default value is null
      See Also:

    • getDisplayItem

      public StaticTextItem getDisplayItem()
      The StaticTextItem created automatically and displayed in the displayForm when canEdit is false and the field type is "blob".

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via fileItem.displayItemDefaults and fileItem.displayItemProperties.

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

      Returns:
      Current displayItem value. Default value is null
      See Also:

    • setDownloadIconSrc

      public FileItem setDownloadIconSrc(String downloadIconSrc)
      Returns the URL for an Icon that will allow the file to be downloaded
      Parameters:
      downloadIconSrc - New downloadIconSrc value. Default value is "[SKIN]actions/download.png"
      Returns:
      FileItem instance, for chaining setter calls
      See Also:

    • getDownloadIconSrc

      public String getDownloadIconSrc()
      Returns the URL for an Icon that will allow the file to be downloaded
      Returns:
      Current downloadIconSrc value. Default value is "[SKIN]actions/download.png"
      See Also:

    • getEditForm

      public DynamicForm getEditForm()
      The DynamicForm created automatically when canEdit is true. Displays a single item for manipulating a file.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via fileItem.editFormDefaults and fileItem.editFormProperties.

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

      Returns:
      Current editForm value. Default value is null
      See Also:

    • setEditProxyConstructor

      public FileItem setEditProxyConstructor(String editProxyConstructor)
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Overrides:
      setEditProxyConstructor in class FormItem
      Parameters:
      editProxyConstructor - New editProxyConstructor value. Default value is "FileItemEditProxy"
      Returns:
      FileItem instance, for chaining setter calls
      See Also:

    • getEditProxyConstructor

      public String getEditProxyConstructor()
      Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
      Overrides:
      getEditProxyConstructor in class FormItem
      Returns:
      Current editProxyConstructor value. Default value is "FileItemEditProxy"
      See Also:

    • setMultiple

      public FileItem setMultiple(Boolean multiple)
      When true, allow the file-selection dialog shelled by the browser to select multiple files.

      Support is not full-cycle at the server - that is, there are server APIs for retrieving each file that was uploaded, but no built-in support for storing multiple files against a single DataSource field. However, you can write custom server DMI code to do something with the files - for instance, you could create multiple new DataSource records for each file via a server DMI like this below: 

           String fileNameStr = (String)dsRequest.getValues().get("image_filename").toString();
 
     String[] fileNames = fileNameStr.split(", ");
     List files = dsRequest.getUploadedFiles();
 
     for (int i = 0; i < files.size(); i++) {
         ISCFileItem file = (ISCFileItem)files.get(i);
         InputStream fileData = file.getInputStream();
         DSRequest inner = new DSRequest("mediaLibrary", "add");
         Map values = new HashMap();
         values.put("title", dsRequest.getValues().get("title"));
         values.put("image", fileData);
         values.put("image_filename", fileNames[i]);
         values.put("image_filesize", file.getSize());
         values.put("image_date_created", new Date());
         
         inner.setValues(values);
         inner.execute();
     }
     
     DSResponse dsResponse = new DSResponse();
     
     dsResponse.setStatus(0);
 
     return dsResponse;


      If this method is called after the component has been drawn/initialized: Updates the multiple setting at runtime, propagating it to the Browser's file dialog. Causes a redraw.
      Overrides:
      setMultiple in class CanvasItem
      Parameters:
      multiple - the HTML of the view link. Default value is true
      Returns:
      FileItem instance, for chaining setter calls
      See Also:

    • getMultiple

      public Boolean getMultiple()
      When true, allow the file-selection dialog shelled by the browser to select multiple files.

      Support is not full-cycle at the server - that is, there are server APIs for retrieving each file that was uploaded, but no built-in support for storing multiple files against a single DataSource field. However, you can write custom server DMI code to do something with the files - for instance, you could create multiple new DataSource records for each file via a server DMI like this below: 

           String fileNameStr = (String)dsRequest.getValues().get("image_filename").toString();
 
     String[] fileNames = fileNameStr.split(", ");
     List files = dsRequest.getUploadedFiles();
 
     for (int i = 0; i < files.size(); i++) {
         ISCFileItem file = (ISCFileItem)files.get(i);
         InputStream fileData = file.getInputStream();
         DSRequest inner = new DSRequest("mediaLibrary", "add");
         Map values = new HashMap();
         values.put("title", dsRequest.getValues().get("title"));
         values.put("image", fileData);
         values.put("image_filename", fileNames[i]);
         values.put("image_filesize", file.getSize());
         values.put("image_date_created", new Date());
         
         inner.setValues(values);
         inner.execute();
     }
     
     DSResponse dsResponse = new DSResponse();
     
     dsResponse.setStatus(0);
 
     return dsResponse;
      Overrides:
      getMultiple in class CanvasItem
      Returns:
      Current multiple value. Default value is true
      See Also:

    • setShouldSaveValue

      public FileItem setShouldSaveValue(Boolean shouldSaveValue)
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      setShouldSaveValue in class CanvasItem
      Parameters:
      shouldSaveValue - New shouldSaveValue value. Default value is true
      Returns:
      FileItem instance, for chaining setter calls

    • getShouldSaveValue

      public Boolean getShouldSaveValue()
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      getShouldSaveValue in class CanvasItem
      Returns:
      Current shouldSaveValue value. Default value is true

    • setShowFileInline

      public FileItem setShowFileInline(Boolean showFileInline)
      Indicates whether to stream the image and display it inline or to display the View and Download icons.
      Parameters:
      showFileInline - New showFileInline value. Default value is null
      Returns:
      FileItem instance, for chaining setter calls

    • getShowFileInline

      public Boolean getShowFileInline()
      Indicates whether to stream the image and display it inline or to display the View and Download icons.
      Returns:
      Current showFileInline value. Default value is null

    • getUploadItem

      public UploadItem getUploadItem()
      The UploadItem created automatically and displayed in the editForm when canEdit is true.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via fileItem.uploadItemDefaults and fileItem.uploadItemProperties.

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

      Returns:
      Current uploadItem value. Default value is null
      See Also:

    • setViewIconSrc

      public FileItem setViewIconSrc(String viewIconSrc)
      Returns the URL for an Icon that will allow the file to be viewed.
      Parameters:
      viewIconSrc - New viewIconSrc value. Default value is "[SKIN]actions/view.png"
      Returns:
      FileItem instance, for chaining setter calls
      See Also:

    • getViewIconSrc

      public String getViewIconSrc()
      Returns the URL for an Icon that will allow the file to be viewed.
      Returns:
      Current viewIconSrc value. Default value is "[SKIN]actions/view.png"
      See Also:

    • setDefaultProperties

      public static void setDefaultProperties(FileItem fileItemProperties)
      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:
      fileItemProperties - properties that should be used as new defaults when instances of this class are created
      See Also: